Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ names exact versions, workloads, boundary refusals and process-fault evidence. A
operating systems, Python versions, model servers, native media/reasoning, Gateway joins
and the OpenTelemetry exporter require separate qualification.

## Embeddable web interfaces (source only, not on PyPI)
## Embeddable web interfaces

The public `tether.client` boundary now supplies typed protocols, explicit
`ClientHost` construction and ownership, journal-backed turn results and targeted
Expand All @@ -52,12 +52,21 @@ Optional components are separate artifacts in this repository:
| Framework-free browser transport | `@tether/client` |
| Injected React hooks and replaceable components | `@tether/react`, `@tether/ui` |

These development artifacts are not published releases. Their source, installed
consumer, real browser and live platform evidence is tracked in the
[implementation plan](docs/helix/04-build/web-platform-implementation-plan.md).
The platform-neutral browser journey uses fabricated model/tool data. Databricks
Apps and Lakebase qualification remains separately recorded; local proof does
not qualify a hosted profile.
The three optional Python distributions are published on PyPI at 0.3.2. The
browser packages in this checkout use the `0.2.0-dev.0` development version.
See the [0.3.2 publication receipt](docs/helix/03-test/evidence/release-032-publication-20261108.md).

The implementation plan tracks source, installed consumer, browser and live
platform evidence for the current candidate. The platform-neutral browser
journey uses fabricated model and tool data. Databricks Apps and Lakebase
qualification has its own live receipts. Actual performance measurements are
optional for release acceptance. See the [implementation plan](docs/helix/04-build/web-platform-implementation-plan.md).

For 0.3.x, append a new turn to correct a committed turn and keep existing
sessions in their original runtime. Cross-process followers receive committed
entries as each step commits. A consumer that needs provisional text routes to
the owning worker. Synchronous callers supply their own event-loop bridge, and
approvals are answered one at a time. See the [recorded consumer decisions](docs/helix/01-frame/prd.md#consumer-decisions-recorded-2026-11-08).

## Offline reference client

Expand Down
11 changes: 5 additions & 6 deletions docs/embedding.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,13 @@ protocol.

## Install the core

This guide targets the `0.3.2` release. Published core `0.2.0`
has an earlier client facade without `ClientHost`; it cannot replace this
candidate. Candidate Python interface packages require the exact core cohort.
In the checkout, `uv sync --frozen` resolves that workspace source. The registry
install below applies after a release includes the APIs used in this guide.
Install the published `0.3.2` core. The Python interface packages require this
exact core cohort. Core `0.2.0` exposes an earlier facade without `ClientHost`.
In the checkout, `uv sync --frozen` resolves the workspace source. See the
[0.3.2 publication receipt](helix/03-test/evidence/release-032-publication-20261108.md).

```sh
uv add novirhiza-tether
uv add 'novirhiza-tether==0.3.2'
```

The core package metadata requires Python 3.11 or later. Optional interfaces stay in separate
Expand Down
22 changes: 20 additions & 2 deletions docs/helix/01-frame/prd.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ kind: product

## Summary

Tether is an open-source Python library for building agent harnesses. It provides an asynchronous agent loop with a provider-neutral model port, a typed tool-call interface, durable session management with crash recovery, and telemetry. It exposes the session list and session data to a user interface through a fast in-process Python API (list, read in pages, follow live changes), and it ships a command-line client and a terminal UI that work seconds after cloning the repository. It supports configured local, self-hosted, sovereign or hosted model servers within declared protocol/model subsets, and keeps provider SDKs out of base packaging/public core types while permitting explicitly selected optional adapter SDKs (ADR-012). Python developers and platform teams who embed an agent runtime in their own services use it, keeping their own interface, storage, and policy. Release success is that every port has a dummy and a conformance suite, that recorded conversations replay deterministically through the loop, that a killed turn on a qualified durable profile preserves accepted steps and explicitly reports blocked or unknown outcomes, that a UI lists, reads, and follows sessions within published budgets, and that a developer is using the harness in a terminal within seconds of cloning.
Tether is an open-source Python library for building agent harnesses. It provides an asynchronous agent loop with a provider-neutral model port, a typed tool-call interface, durable session management with crash recovery, and telemetry. It exposes the session list and session data to a user interface through a fast in-process Python API (list, read in pages, follow live changes), and it ships a command-line client and a terminal UI that work seconds after cloning the repository. It supports configured local, self-hosted, sovereign or hosted model servers within declared protocol/model subsets, and keeps provider SDKs out of base packaging/public core types while permitting explicitly selected optional adapter SDKs (ADR-012). Python developers and platform teams who embed an agent runtime in their own services use it, keeping their own interface, storage, and policy. Release success is that every port has a dummy and a conformance suite, that recorded conversations replay deterministically through the loop, that a killed turn on a qualified durable profile preserves accepted steps and explicitly reports blocked or unknown outcomes, that a UI correctly lists, reads, and follows sessions with declared ownership and authorization, and that a developer can use the harness through the documented terminal workflow.

## Problem and Goals

Expand Down Expand Up @@ -423,7 +423,7 @@ before claiming a current performance pass.
### NFR-7 controlled gate and Apps observations — owner decision, 2026-11-02

Keep Databricks Apps network latency observational, outside performance
pass/fail. The current controlled gate has six local profiles and 54 metrics:
pass/fail. Optional controlled qualification has six local profiles and 54 metrics:
POSIX store 7, MemoryFiles store 7, POSIX public client 17, volatile public
client 11, engine 2 and follower memory 10. These require the known-hardware
reservation and independent isolation evidence above. The two Apps handshake
Expand All @@ -440,6 +440,24 @@ failures into passes or fit any numeric cap. All 41 interface acceptance
criteria and all 45 IP-002 tasks remain required. Functional Apps identity,
storage, recovery, privacy and compatibility qualification are unchanged.

### NFR-7 release disposition — owner decision, 2026-11-09

The owner stated, “I don't think this gate should be a blocker.” Actual
performance qualification is optional and does not block implementation,
interface acceptance or release. A release may report performance as unrun,
deferred, incomplete or failed without claiming a current performance pass.
Required functional, security, lifecycle, caller-deadline and genuine-expiry
proof remains unchanged.

The isolated measurement workflow and its deterministic admission, rejection,
separation, privacy and cleanup controls remain required implementation work.
WP-36 closes on that workflow and its controls; it does not require actual
benchmark measurements to pass. Any referenced qualified performance claim
still requires the exact six-profile/54-metric scope, admission and source joins.
Unknown isolation continues to refuse measurement. Apps latency remains
observational. Preserve source27 baselines, source28 failures and all numeric
thresholds as recorded; nonblocking disposition does not relabel their outcomes.

## Acceptance Test Sketches

| Requirement | Scenario | Input | Expected Output |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,15 @@ MUST NOT establish descendant exit or stream EOF.

### 4. Storage and resource qualification

Under PRD NFR-7's 2026-11-09 owner decision, actual performance qualification
MUST NOT block implementation, functional carrier acceptance or release.
Functional identity, authorization, lifecycle, configured caller deadlines and
genuine expiry evidence remain required. Optional performance measurements
MUST retain their actual outcome and the existing isolation/admission rules;
failed, deferred or unrun measurements MUST NOT be presented as a pass. Apps
latency remains observational. Any referenced qualified local performance claim
MUST retain its exact six-profile/54-metric scope and source/admission joins.

The carrier MUST use a declared Tether `LiveStore` and `HistoryProvider` profile. JSONL files on Apps-local storage MUST NOT be presented as restart-durable. A Unity Catalog volume MUST NOT be treated as a journal or generic writable filesystem without separate contract and qualification.

Lakebase or another managed PostgreSQL endpoint MUST be treated as a separate profile from the existing PostgreSQL 18 qualification. The embedder MUST provide explicit schema migration ownership, application roles, authorization/RLS decisions, TLS requirements, connection acquisition and token refresh. The carrier MUST NOT migrate an unmanaged schema or select an application role implicitly during ordinary construction.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -145,8 +145,16 @@ coverage.

## Performance

PRD NFR-7's 2026-11-09 owner decision makes actual performance qualification
optional and nonblocking for implementation, functional carrier acceptance and
release. The isolated workflow and deterministic admission/rejection/privacy/
cleanup controls remain required. Optional measurements retain their actual
outcome and the existing six-profile/54-metric admission contract; Apps latency
remains observational. This changes no identity, lifecycle, caller deadline,
genuine-expiry or storage support requirement.

- **Expected Load**: No tenant, request-rate or session-volume profile has been supplied; do not invent a capacity claim.
- **Response Target**: No latency SLO is selected here. Measure API operation latency, stream batch latency/size, connection acquisition and shutdown report time in the named deployment profile before support claims.
- **Response Target**: No latency SLO is selected here. Measure API operation latency, stream batch latency/size, connection acquisition and shutdown report time in the named deployment profile before performance support claims.
- **Optimizations**: Bound SSE batches and queues; reuse only qualified external connection pools; do not cache authorization across current identity or credential changes.

## Testing
Expand Down
10 changes: 9 additions & 1 deletion docs/helix/03-test/test-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,14 @@ ddx:

## Functional time and coordination policy

Owner decision on 2026-11-09 makes actual performance qualification optional
and nonblocking for implementation and release. Required functional, security,
lifecycle, configured-deadline and genuine-expiry proof remains unchanged.
The isolated workflow and synthetic admission/rejection/separation/privacy/
cleanup controls remain in functional verification; actual measurements remain
outside it. An optional measurement's failed, deferred, incomplete or unrun
outcome is not a performance pass and does not block those delivery gates.

The owner's 2026-11-02 instruction is to let functional tests be slow and to
separate performance qualification onto known hardware without confounding
concurrent work. Audit Python, TypeScript, installed, browser and accessibility
Expand Down Expand Up @@ -190,7 +198,7 @@ Required P0 release capabilities pass their applicable gates before support is c
| Contract/unit | pytest, AnyIO plugin, Hypothesis | Existing selected Python stack; deterministic ports and property-based state exploration | Unmeasured; separate fast deterministic suite | Maintain shared factories and reusable conformance cases |
| Integration | pytest/AnyIO; local HTTP scenario server; PostgreSQL 18 | Proves transport cancellation/framing and actual transactional/fenced store behavior | Unmeasured; process/server startup is isolated | Maintain controlled fault points, no network credentials |
| End to end | Reference CLI/TUI drivers and a subprocess effect recorder | Proves library-to-client behavior, restart, approval and visible effect counts | Unmeasured; fewer critical journeys | Fabricated scenarios and controlled barriers rather than timing sleeps |
| Performance | Existing planned benchmark suite | Protect API latency/memory and context/executor bounds | Baseline required; no claimed timing | Commit measured budgets by workload/profile |
| Performance | Separate opt-in benchmark suite | Qualify API latency/memory and context/executor measurements | Optional qualification; workflow/logic controls remain required | Retain measured budgets and actual outcomes by workload/profile |

**Cost/benefit summary**: Reuse port suites and state-machine properties for most cases; reserve real processes, workers and PostgreSQL for guarantees those boundaries establish. No framework installation or competitor benchmark is a gate. No measured CI/runtime baseline exists in this plan.

Expand Down
14 changes: 13 additions & 1 deletion docs/helix/03-test/test-plans/STP-001-web-platform-acceptance.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ or a reason to delete useful functional assertions.
| US-068-AC2/AC6 deadline and expiry | `tests/test_selected_profile_identity_revocation_convergence.py`, selected identity/expiry scripts | Controlled-clock single-budget propagation for deterministic tests; exact principal/state and fresh Me before protected refusal while captured token remains unexpired; genuine live OAuth/database expiry with expired/fresh controls. Watchdog exhaustion is incomplete. |
| NFR-7 measurement logic / functional inventory | `tests/test_client_benchmark.py`, `tests/test_web_benchmark.py`, `tests/test_benchmark_store_profiles.py`, `tests/test_benchmark_reconnect.py`, `tests/test_benchmark_follower_memory.py`, related benchmark/ratchet tests | Keep fixture correctness, cursor replay, retention/reset, schema/source validation, rejection and cleanup controls using synthetic measurements or untimed functional helpers. Select real measurement workloads only through the explicit isolated performance path; inventory moved nodes without silently skipping required coverage. |

Owner decision on 2026-11-02 allocates NFR-7 performance closure to six local
Owner decision on 2026-11-02 allocates optional NFR-7 qualification to six local
controlled profiles and exactly 54 metric nodes: store 7, memory-store 7,
client 17, volatile-client 11, engine 2 and follower-memory 10. The two Apps
latencies remain optional observations with provenance and explicit unknown
Expand All @@ -154,6 +154,18 @@ precollected Apps observation. Historical seven-profile/56-node receipts and
source28 failures are retained unchanged. This does not change any of the 41
functional AC rows or the 45 IP-002 tasks.

Owner decision on 2026-11-09 removes actual performance qualification as an
implementation, acceptance or release blocker. WP-36's required proof is the
isolated workflow and its deterministic controls, not a measured performance
PASS. `tests/packaging/test_performance_admission.py` and
`tests/packaging/test_performance_gate.py` retain admission, rejection, privacy,
separation and cleanup checks. Closure controls in
`tests/packaging/test_acceptance_closure.py` must accept completed WP-36 evidence
with those controls and no benchmark nodes, while rejecting malformed or partial
referenced qualified ratchets. Such references still require the exact 54-node
set and strict source/admission joins. Optional failed, deferred, incomplete and
unrun outcomes stay explicit and cannot satisfy a required functional receipt.

NFR-7 admission controls fabricate reservation, host/runtime binding, lock
contention, observer unavailability and interference before/during/after a run.
Require fail-closed deferral or invalidation, retained exact child cleanup and no
Expand Down
15 changes: 14 additions & 1 deletion docs/helix/03-test/web-platform-test-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,14 @@ unbounded wait on an impossible event.

## NFR-7 reference measurement contract

Owner decision on 2026-11-09 makes actual performance qualification optional
and nonblocking for implementation, interface acceptance and release. WP-36
requires an available isolated workflow plus deterministic admission, rejection,
separation, privacy and cleanup controls. It does not require measured metrics
to pass. All 41 functional ACs and all 45 task IDs remain required. Required
functional/profile receipts remain strict; optional measurement status cannot
replace functional, security, lifecycle, caller-deadline or genuine-expiry proof.

The owner's 2026-11-02 isolation constraint governs future performance
qualification. Actual benchmark workloads run only through the explicit
performance path with known reference hardware, exclusive admission and recorded
Expand Down Expand Up @@ -221,10 +229,15 @@ and co-tenancy remain unknown. No new remote infrastructure or controlled
backend qualification follows from this decision.

The historical seven-profile/56-metric files and source28 failures remain
unchanged. Current closure requires exactly the 54 controlled metric nodes;
unchanged. Any referenced qualified performance set requires exactly the 54 controlled metric nodes;
Apps observations cannot fill missing controlled nodes or count as passed
performance criteria. All 41 functional ACs and all 45 IP-002 tasks remain
required, including the separate live Apps behavior/compatibility proofs.
Acceptance closure may instead prove WP-36 with the isolated workflow's
deterministic controls and no qualified metric nodes. An absent, deferred,
incomplete or failed optional measurement is disclosed separately and does not
block release. Referenced qualified claims still require strict complete
metric, baseline, source, hash and admission validation.
The [current controlled-node policy](../04-build/evidence/web-platform/reference-performance/controlled-policy-20261102.json)
lists the exact 54 expected nodes. It is a planning contract, not executed proof.
Each current qualified ratchet must join the final admission record by exact
Expand Down
Loading
Loading