@open-matrix/agents (1.1.33)
Installation
@open-matrix:registry=npm install @open-matrix/agents@1.1.33"@open-matrix/agents": "1.1.33"About this package
Agents service
The agents root owns conversation sessions and forwards prompts to the selected
agent child. Asking a person and a failed run each persist one notification
source in the existing SQLite store. Question cards say <agent> is asking you
and open Chat at the conversation's ?resume= route. Answering, cancelling, superseding, deleting the session or
ending the run acknowledges outstanding questions. On restart, interrupted
questions are acknowledged before delivery replay. Failure cards contain a
generic summary and open the conversation for details. The existing stale-run
reaper records a failed run before dropping its pending execution.
Agents project their durable facts using notification.agent.project through
the hosted notification facade. The broker-delivered tenant subject supplies the
home; the facade rejects conflicting roots and stamps both home fields before
forwarding to the private central notifications actor. This is tenant authority
over its own inbox, not an assertion that the transport distinguishes an agent
from a browser peer in that same home. It permits only agent question/failure
cards, Chat conversation links and acknowledgement, never device/access sources
or management actions. No user token is persisted and no new credential is issued.
Facts retain up to 1,000 delivered events and at most 10,000 total events per home for 30 days. Undelivered facts and acknowledgements survive inbox turnover. At total capacity a new source is explicitly refused and logged; existing question acknowledgements still commit. This bounds storage without silently evicting a pending acknowledgement. Startup and the existing 15-second request reaper replay at most 100 pending facts. Failed deliveries stay pending and produce a warning. Revision fencing keeps an answer pending when an earlier question delivery completes late. The notification owner's separate source markers deduplicate replay after an inbox card is evicted. All source and delivery guarantees are bounded by this 30-day retention window. The runtime must have the installed hosted notification route; a missing responder leaves these bounded source facts pending.
The live child pool is bounded by maxActiveAgents (100 by default). Opening a
conversation at capacity evicts the least recently used idle child; stored
messages and session state remain available for reactivation. A turn in flight,
including one waiting for a person's answer, is never evicted. If every child
is busy, the prompt is refused with that reason. Deleting a conversation stops
its child and frees its slot using the same awaited disposal as clear-all.
Prompt activation and session disposal share a lifecycle queue, so concurrent
prompts cannot exceed the pool limit or evict a newly starting turn.
Run pnpm test for the package suite, including real SQLite ask-and-wait,
failure, replay, restart and retention specifications.
Chat's ticket tools read only the current owned session, replace model-supplied trace and tool claims
with session-owner facts, and show editable proposals before filing. The person can change priority or
drop a proposal; filing reads the live component state. Ticket list and summary default to open statuses
and render the service-owned board component. Every tool shares one five-second end-to-end deadline.
session.replay currently admits only the session owner, replays selected user turns into one new
session in order, and stops at the first refused prompt instead of continuing a partial run. Order P's
consented builder sharing admission will replace the single owner check; replay does not define a
parallel grant interpretation.
Private memory and plan operations require request-local verified caller proof.
Browser calls validate the active bus token through Auth and capability-check the
requested record scope. Server runtimes with no user token carry their public,
account-signed runtime JWT; Memory verifies its issuer, authority, validity and
signed subtree before admitting that scope. The bearer stays in transport-private
state and is injected only while serializing a marked request; no caller token is
installed globally. Pre-tag runtime credentials use the equivalent signed Matrix
runtime metadata until they expire. Raw envelope from and payload mount values
are never identity evidence.
Stored records must also belong to the admitted scope; missing and foreign records
share the same typed not-found response. Nested agent prompts forward their
parent's verified caller proof. Agent tools, WorkstreamActor, and MatrixActor
memory helpers await writes and surface typed refusals. The real-NATS scope
specification proves a forged sender cannot escape either an authenticated user's
scope or a server runtime's signed subtree. Server-started agents persist under
their owned actor mount unless a verified user token delegates the browser scope.
Memory saves carry stable operation ids so a deadline retry returns the original
write rather than duplicating it.
New memory, message, history, title and session-state writes use core's redactSessionContent
and redactSessionState. Titles are redacted before summarising; structured tool
arguments/results and snapshots keep their structure. The rule scans credential
shapes in decoded JSON string values at any depth, preserving ordinary serialized
state bytes and ordinary fields such as secret: "Alex". JSON keys and metadata
identifiers are not scanned; unrecognizable secrets remain outside this shape rule.
Memory content is withheld before SQLite inserts and full-text indexing, including
the v1 record-to-memory schema migration. memory.save also withholds before sending
text to the embedding provider, so its cache hash covers the stored text. Direct
embed.generate, embed.batch and embed.search withhold before provider input
and cache hashing; memory.search withholds its query before dispatch, logging
and replies. On store open, legacy unmarked cache and memory vectors are discarded
because they cannot be re-redacted. Legacy memories content is withheld once and
its full-text index rebuilt in the same transaction. New memory and vector writes
carry content_withheld, so reopening preserves safe rows and vectors. Shared
publications withhold before computing the content and operation digests; evidence
verification authenticates the original owner result digest and compares withheld
text. New publication rows contain those same withheld bytes. Reads and lists
also withhold legacy publication content before query matching and pagination.
Reads, lists, revocations and replayed receipts return the withheld content digest;
stored publication rows, original receipts and evidence digests remain unchanged.
The sealed-home session merge applies the same content/state helpers row by row to
titles, messages, tool arguments/results and state, preserving collision precedence
and timestamps. The v1 migration copies data and drops its source tables in one
transaction: any failed step retains the sources and rolls back destination writes.
Boot retries retained sources even when v2 tables already exist.
The unused activity-frame append methods have been removed from both session
adapters; their legacy readers remain.
Prompt assembly (AgentsRoot._loadSession), SessionPersistence and authenticated
session.history retain legacy read-side withholding. Stored named markers still
count as withheld entries, without flattening already-safe structured tool data.
The in-process regression in environment-harness-binding.spec.ts covers both
legacy rows and new writes; session-write-redaction.spec.ts checks raw SQLite
rows and digest-verified export pages. history-write-redaction.spec.ts checks the
file and record adapters, including titles and snapshots.
Existing v2 rows are unchanged and still need read protection. Principal-state exports and imports preserve their digest-verified bytes: exports of new writes contain the stored markers, while old rows, backups and migration imports can still carry credentials. An in-place redaction migration would change durable data and digests; its selection belongs to the coordinator.
Conversation list pages
$sessionList accepts targetKey or principalId, plus optional cursor and
limit. Pages default to 50, clamp to 1–100, and order by last activity then
session ID descending. Pass the returned nextCursor unchanged to fetch older
conversations; its absence means the end. Cursors retain the ordering values,
so deleting the boundary conversation does not skip the following page. Every
page retains the existing tenant/selection checks. There is no title-search
operation yet; that is tracked in the Chat title-search queue item.
Shared conversation reads
Cross-home session.list and session.history reads call the exported
admitSessionRead rule (session.history selects this path with
sharedRead: true; retained-executor reads keep their separate scoped proof).
The rule sends the presented bus token and the session store's owner—not a
payload identity—to system.auth.introspect. Owners remain admitted. A builder
must be a verified platform operator and the owner must currently have sharing
enabled; the auth owner records the operator, owner, operation and session in
the audit ledger before the read is allowed. Replies retain roles, answerer,
tool-call and trace metadata while applying the shared credential withholding
rule. $sessionList remains Chat's home-scoped paging operation.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @mariozechner/pi-ai | ^0.52.7 |
| @open-matrix/codex-agent | 1.1.33 |
| @open-matrix/contracts | 1.1.33 |
| @open-matrix/conversation | 1.1.33 |
| @open-matrix/core | 1.1.33 |
| @open-matrix/package-artifacts | 1.1.33 |
| @open-matrix/subjects | 1.1.33 |
| @open-matrix/system-observability | 1.1.33 |
| @open-matrix/system-sqlite | 1.1.33 |
Development Dependencies
| ID | Version |
|---|---|
| @matrix/test-utils | 1.1.33 |
| @open-matrix/credential-plane | 1.1.33 |
| @open-matrix/nats-auth | 1.1.33 |
| @open-matrix/package-runtime | 1.1.33 |
| @open-matrix/runtime-control | 1.1.33 |
| @open-matrix/system-auth | 1.1.33 |
| @types/node | ^20.0.0 |
| esbuild | ^0.25.0 |
| nats | ^2.29.3 |
| tsx | ^4.22.4 |
| typescript | ^5.7.0 |