@covia/covia-sdk 1.12.0 → 1.14.0

package/dist/index.d.mts

@@ -24,6 +24,12 @@ declare class Agent {
     listSessions(options?: AgentSessionListOptions): Promise<AgentSessionPage>;
     /** Read one session through the job-free workspace Values API. */
     getSession(sessionId: string): Promise<AgentSession>;
+    /** Stream this agent's run-loop events. See `AgentManager.events`. */
+    events(options?: {
+        sessionId?: string;
+        detail?: boolean;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentEvent>;
     /**
      * Fork this agent into a new agent.
      * @param agentId - ID for the new forked agent
@@ -100,7 +106,9 @@ declare class Job {
      * Stream server-sent events for this job.
      * @returns AsyncGenerator yielding SSEEvent objects
      */
-    stream(): AsyncGenerator<SSEEvent>;
+    stream(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SSEEvent>;
     /**
      * Whether the job is paused (PAUSED, INPUT_REQUIRED, or AUTH_REQUIRED)
      */
@@ -365,6 +373,7 @@ interface AgentManagerVenue extends VenueRequestContext {
 declare class AgentManager {
     private venue;
     private agentsGetSupported;
+    private agentSseSupported;
     constructor(venue: AgentManagerVenue);
     /** Whether the venue serves `GET /api/v1/agents`: no if a probe already
      *  404'd, or if the venue's last known status identifies it as pre-0.4. */
@@ -413,6 +422,20 @@ declare class AgentManager {
     /** Agent info. **Job-free** on covia ≥ 0.4 (`GET /api/v1/agents/{id}`,
      *  covia#180); older venues require an explicit compatibility opt-in. */
     info(agentId: string): Promise<AgentInfoResult>;
+    /**
+     * Stream this agent's run-loop events (run/cycle boundaries, inferences,
+     * tool calls, status changes) from the venue's live tap (covia#394,
+     * venue ≥ 0.9.7). Narrow to one session with `sessionId`; omit owner-only
+     * tool input/result and appended-turn detail with `detail: false`. Pass
+     * `signal` to abort — reader cancellation on abort or early exit is
+     * handled by `parseSSEStream` (covia-sdk#30).
+     * @throws {UnsupportedVenueFeatureError} on venues before 0.9.7.
+     */
+    events(agentId: string, options?: {
+        sessionId?: string;
+        detail?: boolean;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentEvent>;
     /**
      * Page an agent's sessions directly from `g/<agentId>/sessions`.
      * This is a job-free Values read; session adapter-specific fields remain
@@ -439,7 +462,9 @@ declare class JobManager {
     pause(jobId: string): Promise<JobMetadata>;
     resume(jobId: string): Promise<JobMetadata>;
     sendMessage(jobId: string, message: unknown): Promise<unknown>;
-    stream(jobId: string): AsyncGenerator<SSEEvent>;
+    stream(jobId: string, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SSEEvent>;
 }
 
 interface AssetManagerVenue extends VenueRequestContext {
@@ -764,6 +789,45 @@ declare class DLFSManager {
     getContent(drive: string, path: string): Promise<ReadableStream<Uint8Array>>;
 }
 
+interface UserManagerVenue extends VenueRequestContext {
+    operations: OperationRunner;
+    lastKnownStatus?: StatusData;
+}
+declare class UserManager {
+    private venue;
+    private usersSupported;
+    constructor(venue: UserManagerVenue);
+    /** A job-free users GET that rejects when the endpoint is unavailable. */
+    private usersGet;
+    /**
+     * List registered venue users. **Job-free** on covia venues serving
+     * `GET /api/v1/users` (covia#255) — synchronous, no Job persisted.
+     * Operator-only: throws a `GridError` with `statusCode` 403 for a
+     * signed-in caller that is not the venue itself and holds no venue-issued
+     * delegation over `<venueDID>/users` — that is an expected, common
+     * outcome to branch on, not a bug.
+     */
+    list(): Promise<UserListResult>;
+    /**
+     * Get one registered user. The caller's own DID needs no operator
+     * authority; any other DID does (403 otherwise).
+     */
+    info(did: string): Promise<UserInfo>;
+    /**
+     * List a venue-managed user's authenticators, active and revoked
+     * tombstones alike — revocation is a status transition in place, never a
+     * deletion. The caller's own DID needs no operator authority; any other
+     * DID does (403 otherwise).
+     */
+    listAuthenticators(did: string): Promise<AuthenticationKeysResult>;
+    /**
+     * Revoke one of a venue-managed user's authenticators. A mutation, so —
+     * unlike the reads above — this goes through `operations.run` and mints a
+     * Job, matching every other write in this SDK (e.g. `SecretManager.set`).
+     */
+    revokeAuthenticator(key: string, did?: string, ucans?: string[]): Promise<AuthenticatorRevokeResult>;
+}
+
 /**
  * Resolve a non-DID venue id into the ordered list of base URLs that
  * {@link Venue.connect} will try in turn. Explicit `http(s)://` inputs are
@@ -819,6 +883,7 @@ declare class Venue implements VenueInterface {
     private _skills?;
     private _memory?;
     private _dlfs?;
+    private _users?;
     get adapters(): AdapterManager;
     get agents(): AgentManager;
     get jobs(): JobManager;
@@ -830,6 +895,7 @@ declare class Venue implements VenueInterface {
     get skills(): SkillManager;
     get memory(): MemoryManager;
     get dlfs(): DLFSManager;
+    get users(): UserManager;
     constructor(options?: VenueOptions);
     /**
      * Connect to a venue, validating it with `GET {base}/api/v1/status`. If the
@@ -1074,6 +1140,12 @@ interface StatusData {
     /** Venue platform version (e.g. "0.3.0"). Absent on venues before 0.3. */
     version?: string;
     stats?: StatsData;
+    /** Curated admission-policy fields (#255) — safe to state to any caller.
+     *  Absent on venues before this shipped; treat as unknown, not false. */
+    access?: {
+        public: boolean;
+        userAutoCreate: boolean;
+    };
 }
 interface StatsData {
     assets?: number;
@@ -1337,6 +1409,99 @@ interface AgentFailTaskResult {
     taskId: string;
     status: string;
 }
+/** Fields present on every agent run-loop event frame (covia#394). */
+interface AgentEventEnvelope {
+    seq: number;
+    ts: number;
+    agentId: string;
+    address: string;
+}
+interface AgentRunStartEvent extends AgentEventEnvelope {
+    type: 'run:start';
+    run: number;
+}
+interface AgentRunEndEvent extends AgentEventEnvelope {
+    type: 'run:end';
+    run: number;
+    status: AgentStatus;
+    cycles: number;
+}
+interface AgentCycleStartEvent extends AgentEventEnvelope {
+    type: 'cycle:start';
+    run: number;
+    cycle: number;
+    op?: string;
+    sessionId?: string;
+    jobId?: string;
+    jobs?: string[];
+    tasks: unknown;
+    messages: unknown;
+    pending: unknown;
+}
+interface AgentCycleEndEvent extends AgentEventEnvelope {
+    type: 'cycle:end';
+    run: number;
+    cycle: number;
+    ms: number;
+    response?: unknown;
+    error?: string;
+    tokens?: unknown;
+    timeline?: unknown;
+    detail?: {
+        turns: unknown;
+    };
+}
+interface AgentInferenceStartEvent extends AgentEventEnvelope {
+    type: 'inference:start';
+    op: string;
+    model?: string;
+    messages: unknown;
+    tools: unknown;
+    bytes: number;
+    budget: unknown;
+    depth?: number;
+}
+interface AgentInferenceEndEvent extends AgentEventEnvelope {
+    type: 'inference:end';
+    ms: number;
+    model?: string;
+    content?: unknown;
+    toolCalls?: {
+        id: string;
+        name: string;
+    }[];
+    tokens?: unknown;
+    error?: string;
+    depth?: number;
+}
+interface AgentToolStartEvent extends AgentEventEnvelope {
+    type: 'tool:start';
+    id: string;
+    name: string;
+    depth?: number;
+    detail: {
+        input: unknown;
+    };
+}
+interface AgentToolResultEvent extends AgentEventEnvelope {
+    type: 'tool:result';
+    id: string;
+    name: string;
+    ms: number;
+    isError?: boolean;
+    depth?: number;
+    detail: {
+        result: unknown;
+    };
+}
+interface AgentStatusEvent extends AgentEventEnvelope {
+    type: 'status';
+    status: AgentStatus;
+    error?: string;
+}
+/** One frame from the venue's agent run-loop event stream (`GET
+ *  /agents/{id}/sse`, covia#394), discriminated on `type`. */
+type AgentEvent = AgentRunStartEvent | AgentRunEndEvent | AgentCycleStartEvent | AgentCycleEndEvent | AgentInferenceStartEvent | AgentInferenceEndEvent | AgentToolStartEvent | AgentToolResultEvent | AgentStatusEvent;
 interface AssetPinResult {
     path: string;
     hash: string;
@@ -1527,6 +1692,50 @@ interface DLFSListResult {
     entries: DLFSEntry[];
     warnings?: string[];
 }
+interface UserSummary {
+    did: string;
+    registered: boolean;
+    /** True for a venue-managed named account (a did:web identity minted from
+     *  a username); false/absent for a plain registered DID. */
+    managed?: boolean;
+    meta?: Record<string, unknown>;
+}
+interface UserListResult {
+    users: UserSummary[];
+    total: number;
+}
+interface UserInfo {
+    did: string;
+    registered: boolean;
+    managed?: boolean;
+    meta?: Record<string, unknown>;
+}
+/** One authenticator's lifecycle record. Revocation is a status transition
+ *  in place — a revoked entry is retained forever, never deleted, so the
+ *  key's full add/revoke history stays visible as an audit tombstone. */
+interface AuthenticationKeyEntry {
+    status: "active" | "revoked";
+    /** Epoch millis. */
+    addedAt: number;
+    /** Actor DID that added this key. */
+    addedBy: string;
+    label?: string;
+    /** Epoch millis, present only once status is "revoked". */
+    revokedAt?: number;
+    /** Actor DID that revoked this key, present only once status is "revoked". */
+    revokedBy?: string;
+}
+/** Keyed by the authenticator's own `did:key:...` string. */
+type AuthenticationKeysMap = Record<string, AuthenticationKeyEntry>;
+interface AuthenticationKeysResult {
+    did: string;
+    authenticationKeys: AuthenticationKeysMap;
+}
+interface AuthenticatorRevokeResult {
+    did: string;
+    key: string;
+    revoked: boolean;
+}
 interface FunctionInfo {
     name: string;
     id: string;
@@ -1702,9 +1911,13 @@ declare function createSSEEvent(fields: {
 }): SSEEvent;
 /**
  * Parse an SSE stream from a fetch Response body.
- * Yields SSEEvent objects as they arrive.
+ * Yields SSEEvent objects as they arrive. On `signal` abort, iteration ends
+ * as if the stream closed (no exception thrown); callers that must
+ * distinguish should check `signal.aborted` after the loop.
  */
-declare function parseSSEStream(response: Response): AsyncGenerator<SSEEvent>;
+declare function parseSSEStream(response: Response, options?: {
+    signal?: AbortSignal;
+}): AsyncGenerator<SSEEvent>;
 
 /**
  * DID and lattice-path helpers for the Covia grid.
@@ -1934,4 +2147,4 @@ declare function grant(ownerPrivateKey: Uint8Array, audienceDID: string, withRes
  */
 declare function relayDelegation(privateKey: Uint8Array, venueDID: string, lifetimeSeconds: number, caps?: UCANCapability[]): string;
 
-export { type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentDeleteInput, type AgentDeleteResult, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentSession, type AgentSessionListOptions, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, AgentStatus, type AgentSuspendResult, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };
+export { type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentCycleEndEvent, type AgentCycleStartEvent, type AgentDeleteInput, type AgentDeleteResult, type AgentEvent, type AgentEventEnvelope, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInferenceEndEvent, type AgentInferenceStartEvent, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentRunEndEvent, type AgentRunStartEvent, type AgentSession, type AgentSessionListOptions, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, AgentStatus, type AgentStatusEvent, type AgentSuspendResult, type AgentToolResultEvent, type AgentToolStartEvent, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, type AuthenticationKeyEntry, type AuthenticationKeysMap, type AuthenticationKeysResult, type AuthenticatorRevokeResult, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, type UserInfo, type UserListResult, UserManager, type UserSummary, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };

package/dist/index.d.ts

@@ -24,6 +24,12 @@ declare class Agent {
     listSessions(options?: AgentSessionListOptions): Promise<AgentSessionPage>;
     /** Read one session through the job-free workspace Values API. */
     getSession(sessionId: string): Promise<AgentSession>;
+    /** Stream this agent's run-loop events. See `AgentManager.events`. */
+    events(options?: {
+        sessionId?: string;
+        detail?: boolean;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentEvent>;
     /**
      * Fork this agent into a new agent.
      * @param agentId - ID for the new forked agent
@@ -100,7 +106,9 @@ declare class Job {
      * Stream server-sent events for this job.
      * @returns AsyncGenerator yielding SSEEvent objects
      */
-    stream(): AsyncGenerator<SSEEvent>;
+    stream(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SSEEvent>;
     /**
      * Whether the job is paused (PAUSED, INPUT_REQUIRED, or AUTH_REQUIRED)
      */
@@ -365,6 +373,7 @@ interface AgentManagerVenue extends VenueRequestContext {
 declare class AgentManager {
     private venue;
     private agentsGetSupported;
+    private agentSseSupported;
     constructor(venue: AgentManagerVenue);
     /** Whether the venue serves `GET /api/v1/agents`: no if a probe already
      *  404'd, or if the venue's last known status identifies it as pre-0.4. */
@@ -413,6 +422,20 @@ declare class AgentManager {
     /** Agent info. **Job-free** on covia ≥ 0.4 (`GET /api/v1/agents/{id}`,
      *  covia#180); older venues require an explicit compatibility opt-in. */
     info(agentId: string): Promise<AgentInfoResult>;
+    /**
+     * Stream this agent's run-loop events (run/cycle boundaries, inferences,
+     * tool calls, status changes) from the venue's live tap (covia#394,
+     * venue ≥ 0.9.7). Narrow to one session with `sessionId`; omit owner-only
+     * tool input/result and appended-turn detail with `detail: false`. Pass
+     * `signal` to abort — reader cancellation on abort or early exit is
+     * handled by `parseSSEStream` (covia-sdk#30).
+     * @throws {UnsupportedVenueFeatureError} on venues before 0.9.7.
+     */
+    events(agentId: string, options?: {
+        sessionId?: string;
+        detail?: boolean;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentEvent>;
     /**
      * Page an agent's sessions directly from `g/<agentId>/sessions`.
      * This is a job-free Values read; session adapter-specific fields remain
@@ -439,7 +462,9 @@ declare class JobManager {
     pause(jobId: string): Promise<JobMetadata>;
     resume(jobId: string): Promise<JobMetadata>;
     sendMessage(jobId: string, message: unknown): Promise<unknown>;
-    stream(jobId: string): AsyncGenerator<SSEEvent>;
+    stream(jobId: string, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SSEEvent>;
 }
 
 interface AssetManagerVenue extends VenueRequestContext {
@@ -764,6 +789,45 @@ declare class DLFSManager {
     getContent(drive: string, path: string): Promise<ReadableStream<Uint8Array>>;
 }
 
+interface UserManagerVenue extends VenueRequestContext {
+    operations: OperationRunner;
+    lastKnownStatus?: StatusData;
+}
+declare class UserManager {
+    private venue;
+    private usersSupported;
+    constructor(venue: UserManagerVenue);
+    /** A job-free users GET that rejects when the endpoint is unavailable. */
+    private usersGet;
+    /**
+     * List registered venue users. **Job-free** on covia venues serving
+     * `GET /api/v1/users` (covia#255) — synchronous, no Job persisted.
+     * Operator-only: throws a `GridError` with `statusCode` 403 for a
+     * signed-in caller that is not the venue itself and holds no venue-issued
+     * delegation over `<venueDID>/users` — that is an expected, common
+     * outcome to branch on, not a bug.
+     */
+    list(): Promise<UserListResult>;
+    /**
+     * Get one registered user. The caller's own DID needs no operator
+     * authority; any other DID does (403 otherwise).
+     */
+    info(did: string): Promise<UserInfo>;
+    /**
+     * List a venue-managed user's authenticators, active and revoked
+     * tombstones alike — revocation is a status transition in place, never a
+     * deletion. The caller's own DID needs no operator authority; any other
+     * DID does (403 otherwise).
+     */
+    listAuthenticators(did: string): Promise<AuthenticationKeysResult>;
+    /**
+     * Revoke one of a venue-managed user's authenticators. A mutation, so —
+     * unlike the reads above — this goes through `operations.run` and mints a
+     * Job, matching every other write in this SDK (e.g. `SecretManager.set`).
+     */
+    revokeAuthenticator(key: string, did?: string, ucans?: string[]): Promise<AuthenticatorRevokeResult>;
+}
+
 /**
  * Resolve a non-DID venue id into the ordered list of base URLs that
  * {@link Venue.connect} will try in turn. Explicit `http(s)://` inputs are
@@ -819,6 +883,7 @@ declare class Venue implements VenueInterface {
     private _skills?;
     private _memory?;
     private _dlfs?;
+    private _users?;
     get adapters(): AdapterManager;
     get agents(): AgentManager;
     get jobs(): JobManager;
@@ -830,6 +895,7 @@ declare class Venue implements VenueInterface {
     get skills(): SkillManager;
     get memory(): MemoryManager;
     get dlfs(): DLFSManager;
+    get users(): UserManager;
     constructor(options?: VenueOptions);
     /**
      * Connect to a venue, validating it with `GET {base}/api/v1/status`. If the
@@ -1074,6 +1140,12 @@ interface StatusData {
     /** Venue platform version (e.g. "0.3.0"). Absent on venues before 0.3. */
     version?: string;
     stats?: StatsData;
+    /** Curated admission-policy fields (#255) — safe to state to any caller.
+     *  Absent on venues before this shipped; treat as unknown, not false. */
+    access?: {
+        public: boolean;
+        userAutoCreate: boolean;
+    };
 }
 interface StatsData {
     assets?: number;
@@ -1337,6 +1409,99 @@ interface AgentFailTaskResult {
     taskId: string;
     status: string;
 }
+/** Fields present on every agent run-loop event frame (covia#394). */
+interface AgentEventEnvelope {
+    seq: number;
+    ts: number;
+    agentId: string;
+    address: string;
+}
+interface AgentRunStartEvent extends AgentEventEnvelope {
+    type: 'run:start';
+    run: number;
+}
+interface AgentRunEndEvent extends AgentEventEnvelope {
+    type: 'run:end';
+    run: number;
+    status: AgentStatus;
+    cycles: number;
+}
+interface AgentCycleStartEvent extends AgentEventEnvelope {
+    type: 'cycle:start';
+    run: number;
+    cycle: number;
+    op?: string;
+    sessionId?: string;
+    jobId?: string;
+    jobs?: string[];
+    tasks: unknown;
+    messages: unknown;
+    pending: unknown;
+}
+interface AgentCycleEndEvent extends AgentEventEnvelope {
+    type: 'cycle:end';
+    run: number;
+    cycle: number;
+    ms: number;
+    response?: unknown;
+    error?: string;
+    tokens?: unknown;
+    timeline?: unknown;
+    detail?: {
+        turns: unknown;
+    };
+}
+interface AgentInferenceStartEvent extends AgentEventEnvelope {
+    type: 'inference:start';
+    op: string;
+    model?: string;
+    messages: unknown;
+    tools: unknown;
+    bytes: number;
+    budget: unknown;
+    depth?: number;
+}
+interface AgentInferenceEndEvent extends AgentEventEnvelope {
+    type: 'inference:end';
+    ms: number;
+    model?: string;
+    content?: unknown;
+    toolCalls?: {
+        id: string;
+        name: string;
+    }[];
+    tokens?: unknown;
+    error?: string;
+    depth?: number;
+}
+interface AgentToolStartEvent extends AgentEventEnvelope {
+    type: 'tool:start';
+    id: string;
+    name: string;
+    depth?: number;
+    detail: {
+        input: unknown;
+    };
+}
+interface AgentToolResultEvent extends AgentEventEnvelope {
+    type: 'tool:result';
+    id: string;
+    name: string;
+    ms: number;
+    isError?: boolean;
+    depth?: number;
+    detail: {
+        result: unknown;
+    };
+}
+interface AgentStatusEvent extends AgentEventEnvelope {
+    type: 'status';
+    status: AgentStatus;
+    error?: string;
+}
+/** One frame from the venue's agent run-loop event stream (`GET
+ *  /agents/{id}/sse`, covia#394), discriminated on `type`. */
+type AgentEvent = AgentRunStartEvent | AgentRunEndEvent | AgentCycleStartEvent | AgentCycleEndEvent | AgentInferenceStartEvent | AgentInferenceEndEvent | AgentToolStartEvent | AgentToolResultEvent | AgentStatusEvent;
 interface AssetPinResult {
     path: string;
     hash: string;
@@ -1527,6 +1692,50 @@ interface DLFSListResult {
     entries: DLFSEntry[];
     warnings?: string[];
 }
+interface UserSummary {
+    did: string;
+    registered: boolean;
+    /** True for a venue-managed named account (a did:web identity minted from
+     *  a username); false/absent for a plain registered DID. */
+    managed?: boolean;
+    meta?: Record<string, unknown>;
+}
+interface UserListResult {
+    users: UserSummary[];
+    total: number;
+}
+interface UserInfo {
+    did: string;
+    registered: boolean;
+    managed?: boolean;
+    meta?: Record<string, unknown>;
+}
+/** One authenticator's lifecycle record. Revocation is a status transition
+ *  in place — a revoked entry is retained forever, never deleted, so the
+ *  key's full add/revoke history stays visible as an audit tombstone. */
+interface AuthenticationKeyEntry {
+    status: "active" | "revoked";
+    /** Epoch millis. */
+    addedAt: number;
+    /** Actor DID that added this key. */
+    addedBy: string;
+    label?: string;
+    /** Epoch millis, present only once status is "revoked". */
+    revokedAt?: number;
+    /** Actor DID that revoked this key, present only once status is "revoked". */
+    revokedBy?: string;
+}
+/** Keyed by the authenticator's own `did:key:...` string. */
+type AuthenticationKeysMap = Record<string, AuthenticationKeyEntry>;
+interface AuthenticationKeysResult {
+    did: string;
+    authenticationKeys: AuthenticationKeysMap;
+}
+interface AuthenticatorRevokeResult {
+    did: string;
+    key: string;
+    revoked: boolean;
+}
 interface FunctionInfo {
     name: string;
     id: string;
@@ -1702,9 +1911,13 @@ declare function createSSEEvent(fields: {
 }): SSEEvent;
 /**
  * Parse an SSE stream from a fetch Response body.
- * Yields SSEEvent objects as they arrive.
+ * Yields SSEEvent objects as they arrive. On `signal` abort, iteration ends
+ * as if the stream closed (no exception thrown); callers that must
+ * distinguish should check `signal.aborted` after the loop.
  */
-declare function parseSSEStream(response: Response): AsyncGenerator<SSEEvent>;
+declare function parseSSEStream(response: Response, options?: {
+    signal?: AbortSignal;
+}): AsyncGenerator<SSEEvent>;
 
 /**
  * DID and lattice-path helpers for the Covia grid.
@@ -1934,4 +2147,4 @@ declare function grant(ownerPrivateKey: Uint8Array, audienceDID: string, withRes
  */
 declare function relayDelegation(privateKey: Uint8Array, venueDID: string, lifetimeSeconds: number, caps?: UCANCapability[]): string;
 
-export { type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentDeleteInput, type AgentDeleteResult, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentSession, type AgentSessionListOptions, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, AgentStatus, type AgentSuspendResult, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };
+export { type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentCycleEndEvent, type AgentCycleStartEvent, type AgentDeleteInput, type AgentDeleteResult, type AgentEvent, type AgentEventEnvelope, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInferenceEndEvent, type AgentInferenceStartEvent, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentRunEndEvent, type AgentRunStartEvent, type AgentSession, type AgentSessionListOptions, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, AgentStatus, type AgentStatusEvent, type AgentSuspendResult, type AgentToolResultEvent, type AgentToolStartEvent, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, type AuthenticationKeyEntry, type AuthenticationKeysMap, type AuthenticationKeysResult, type AuthenticatorRevokeResult, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, type UserInfo, type UserListResult, UserManager, type UserSummary, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };

package/dist/index.js

@@ -1503,7 +1503,7 @@ function createSSEEvent(fields) {
     }
   };
 }
-async function* parseSSEStream(response) {
+async function* parseSSEStream(response, options) {
   const reader = response.body?.getReader();
   if (!reader) return;
   const decoder = new TextDecoder();
@@ -1512,9 +1512,26 @@ async function* parseSSEStream(response) {
   let data = [];
   let id;
   let retry;
+  const signal = options?.signal;
+  const onAbort = () => {
+    void reader.cancel(signal.reason).catch(() => {
+    });
+  };
+  if (signal) {
+    if (signal.aborted) void reader.cancel(signal.reason).catch(() => {
+    });
+    else signal.addEventListener("abort", onAbort, { once: true });
+  }
   try {
     while (true) {
-      const { done, value } = await reader.read();
+      let result;
+      try {
+        result = await reader.read();
+      } catch (err2) {
+        if (signal?.aborted) break;
+        throw err2;
+      }
+      const { done, value } = result;
       if (done) break;
       buffer += decoder.decode(value, { stream: true });
       const lines = buffer.split("\n");
@@ -1569,7 +1586,9 @@ async function* parseSSEStream(response) {
       yield createSSEEvent({ event, data: data.join("\n"), id, retry });
     }
   } finally {
-    reader.releaseLock();
+    signal?.removeEventListener("abort", onAbort);
+    await reader.cancel().catch(() => {
+    });
   }
 }
 
@@ -1746,6 +1765,11 @@ var AgentManager = class {
     // Whether this venue serves GET /api/v1/agents — flipped on the first 404 so
     // pre-0.4 venues pay the probe once, not one failed GET per read (covia#180).
     this.agentsGetSupported = true;
+    // Whether this venue serves GET /api/v1/agents/{id}/sse — flipped on a
+    // route-missing 404 (covia#394 landed in venue 0.9.7). No version fast-path:
+    // versionAtLeast() only resolves major.minor, not the patch precision this
+    // needs, so rely purely on the lazy 404 latch (matches UserManager.usersGet).
+    this.agentSseSupported = true;
   }
   /** Whether the venue serves `GET /api/v1/agents`: no if a probe already
    *  404'd, or if the venue's last known status identifies it as pre-0.4. */
@@ -1848,6 +1872,38 @@ var AgentManager = class {
   async info(agentId) {
     return this.agentsGet(`/${encodeURIComponent(agentId)}`, {});
   }
+  /**
+   * Stream this agent's run-loop events (run/cycle boundaries, inferences,
+   * tool calls, status changes) from the venue's live tap (covia#394,
+   * venue ≥ 0.9.7). Narrow to one session with `sessionId`; omit owner-only
+   * tool input/result and appended-turn detail with `detail: false`. Pass
+   * `signal` to abort — reader cancellation on abort or early exit is
+   * handled by `parseSSEStream` (covia-sdk#30).
+   * @throws {UnsupportedVenueFeatureError} on venues before 0.9.7.
+   */
+  async *events(agentId, options = {}) {
+    if (!this.agentSseSupported) throw new UnsupportedVenueFeatureError("agent event stream");
+    const qs = new URLSearchParams();
+    if (options.sessionId !== void 0) qs.set("sessionId", options.sessionId);
+    if (options.detail !== void 0) qs.set("detail", String(options.detail));
+    const q = qs.toString();
+    let response;
+    try {
+      response = await venueStream(
+        this.venue,
+        `/api/v1/agents/${encodeURIComponent(agentId)}/sse${q ? `?${q}` : ""}`,
+        { headers: { "Accept": "text/event-stream" }, signal: options.signal }
+      );
+    } catch (e) {
+      if (!(e instanceof NotFoundError)) throw e;
+      if (!ROUTE_MISSING_404.test(e.message)) throw e;
+      this.agentSseSupported = false;
+      throw new UnsupportedVenueFeatureError("agent event stream");
+    }
+    for await (const evt of parseSSEStream(response, { signal: options.signal })) {
+      yield evt.json();
+    }
+  }
   /**
    * Page an agent's sessions directly from `g/<agentId>/sessions`.
    * This is a job-free Values read; session adapter-specific fields remain
@@ -1998,8 +2054,8 @@ var Job = class {
    * Stream server-sent events for this job.
    * @returns AsyncGenerator yielding SSEEvent objects
    */
-  async *stream() {
-    yield* this._jobs.stream(this.id);
+  async *stream(options) {
+    yield* this._jobs.stream(this.id, options);
   }
   /**
    * Whether the job is paused (PAUSED, INPUT_REQUIRED, or AUTH_REQUIRED)
@@ -2173,11 +2229,12 @@ var JobManager = class {
       throw error;
     }
   }
-  async *stream(jobId) {
+  async *stream(jobId, options) {
     const response = await venueStream(this.venue, `/api/v1/jobs/${jobId}/sse`, {
-      headers: { "Accept": "text/event-stream" }
+      headers: { "Accept": "text/event-stream" },
+      signal: options?.signal
     });
-    yield* parseSSEStream(response);
+    yield* parseSSEStream(response, { signal: options?.signal });
   }
 };
 
@@ -2851,6 +2908,68 @@ var DLFSManager = class {
   }
 };
 
+// src/UserManager.ts
+var UserManager = class {
+  constructor(venue) {
+    this.venue = venue;
+    // Whether this venue serves GET /api/v1/users — flipped on a route-missing
+    // 404 so a pre-#255 venue pays the probe once, not one failed GET per read.
+    this.usersSupported = true;
+  }
+  /** A job-free users GET that rejects when the endpoint is unavailable. */
+  async usersGet(path) {
+    if (!this.usersSupported) throw new UnsupportedVenueFeatureError("venue users");
+    try {
+      return await venueJson(this.venue, `/api/v1/users${path}`);
+    } catch (e) {
+      if (!(e instanceof NotFoundError)) throw e;
+      const routeMissing = path === "" || ROUTE_MISSING_404.test(e.message);
+      if (!routeMissing) throw e;
+      this.usersSupported = false;
+      throw new UnsupportedVenueFeatureError("venue users");
+    }
+  }
+  /**
+   * List registered venue users. **Job-free** on covia venues serving
+   * `GET /api/v1/users` (covia#255) — synchronous, no Job persisted.
+   * Operator-only: throws a `GridError` with `statusCode` 403 for a
+   * signed-in caller that is not the venue itself and holds no venue-issued
+   * delegation over `<venueDID>/users` — that is an expected, common
+   * outcome to branch on, not a bug.
+   */
+  async list() {
+    return this.usersGet("");
+  }
+  /**
+   * Get one registered user. The caller's own DID needs no operator
+   * authority; any other DID does (403 otherwise).
+   */
+  async info(did) {
+    return this.usersGet(`/${encodeURIComponent(did)}`);
+  }
+  /**
+   * List a venue-managed user's authenticators, active and revoked
+   * tombstones alike — revocation is a status transition in place, never a
+   * deletion. The caller's own DID needs no operator authority; any other
+   * DID does (403 otherwise).
+   */
+  async listAuthenticators(did) {
+    return this.usersGet(`/${encodeURIComponent(did)}/authentications`);
+  }
+  /**
+   * Revoke one of a venue-managed user's authenticators. A mutation, so —
+   * unlike the reads above — this goes through `operations.run` and mints a
+   * Job, matching every other write in this SDK (e.g. `SecretManager.set`).
+   */
+  async revokeAuthenticator(key, did, ucans) {
+    return this.venue.operations.run(
+      "v/ops/user/authentication-revoke",
+      { did, key },
+      { ucans }
+    );
+  }
+};
+
 // src/Agent.ts
 var Agent = class _Agent {
   constructor(id, venue) {
@@ -2900,6 +3019,10 @@ var Agent = class _Agent {
   async getSession(sessionId) {
     return this._agents.getSession(this.id, sessionId);
   }
+  /** Stream this agent's run-loop events. See `AgentManager.events`. */
+  async *events(options) {
+    yield* this._agents.events(this.id, options);
+  }
   /**
    * Fork this agent into a new agent.
    * @param agentId - ID for the new forked agent
@@ -3052,6 +3175,9 @@ var Venue = class _Venue {
   get dlfs() {
     return this._dlfs ?? (this._dlfs = new DLFSManager(this));
   }
+  get users() {
+    return this._users ?? (this._users = new UserManager(this));
+  }
   /**
    * Connect to a venue, validating it with `GET {base}/api/v1/status`. If the
    * venue is auth-gated (status answers 401/403 — public access disabled), the
@@ -3422,6 +3548,7 @@ exports.SecretManager = SecretManager;
 exports.SkillManager = SkillManager;
 exports.UCANManager = UCANManager;
 exports.UnsupportedVenueFeatureError = UnsupportedVenueFeatureError;
+exports.UserManager = UserManager;
 exports.VENUE_RELAY = VENUE_RELAY;
 exports.Venue = Venue;
 exports.VenueIdentityChangedError = VenueIdentityChangedError;

package/dist/index.mjs

@@ -1501,7 +1501,7 @@ function createSSEEvent(fields) {
     }
   };
 }
-async function* parseSSEStream(response) {
+async function* parseSSEStream(response, options) {
   const reader = response.body?.getReader();
   if (!reader) return;
   const decoder = new TextDecoder();
@@ -1510,9 +1510,26 @@ async function* parseSSEStream(response) {
   let data = [];
   let id;
   let retry;
+  const signal = options?.signal;
+  const onAbort = () => {
+    void reader.cancel(signal.reason).catch(() => {
+    });
+  };
+  if (signal) {
+    if (signal.aborted) void reader.cancel(signal.reason).catch(() => {
+    });
+    else signal.addEventListener("abort", onAbort, { once: true });
+  }
   try {
     while (true) {
-      const { done, value } = await reader.read();
+      let result;
+      try {
+        result = await reader.read();
+      } catch (err2) {
+        if (signal?.aborted) break;
+        throw err2;
+      }
+      const { done, value } = result;
       if (done) break;
       buffer += decoder.decode(value, { stream: true });
       const lines = buffer.split("\n");
@@ -1567,7 +1584,9 @@ async function* parseSSEStream(response) {
       yield createSSEEvent({ event, data: data.join("\n"), id, retry });
     }
   } finally {
-    reader.releaseLock();
+    signal?.removeEventListener("abort", onAbort);
+    await reader.cancel().catch(() => {
+    });
   }
 }
 
@@ -1744,6 +1763,11 @@ var AgentManager = class {
     // Whether this venue serves GET /api/v1/agents — flipped on the first 404 so
     // pre-0.4 venues pay the probe once, not one failed GET per read (covia#180).
     this.agentsGetSupported = true;
+    // Whether this venue serves GET /api/v1/agents/{id}/sse — flipped on a
+    // route-missing 404 (covia#394 landed in venue 0.9.7). No version fast-path:
+    // versionAtLeast() only resolves major.minor, not the patch precision this
+    // needs, so rely purely on the lazy 404 latch (matches UserManager.usersGet).
+    this.agentSseSupported = true;
   }
   /** Whether the venue serves `GET /api/v1/agents`: no if a probe already
    *  404'd, or if the venue's last known status identifies it as pre-0.4. */
@@ -1846,6 +1870,38 @@ var AgentManager = class {
   async info(agentId) {
     return this.agentsGet(`/${encodeURIComponent(agentId)}`, {});
   }
+  /**
+   * Stream this agent's run-loop events (run/cycle boundaries, inferences,
+   * tool calls, status changes) from the venue's live tap (covia#394,
+   * venue ≥ 0.9.7). Narrow to one session with `sessionId`; omit owner-only
+   * tool input/result and appended-turn detail with `detail: false`. Pass
+   * `signal` to abort — reader cancellation on abort or early exit is
+   * handled by `parseSSEStream` (covia-sdk#30).
+   * @throws {UnsupportedVenueFeatureError} on venues before 0.9.7.
+   */
+  async *events(agentId, options = {}) {
+    if (!this.agentSseSupported) throw new UnsupportedVenueFeatureError("agent event stream");
+    const qs = new URLSearchParams();
+    if (options.sessionId !== void 0) qs.set("sessionId", options.sessionId);
+    if (options.detail !== void 0) qs.set("detail", String(options.detail));
+    const q = qs.toString();
+    let response;
+    try {
+      response = await venueStream(
+        this.venue,
+        `/api/v1/agents/${encodeURIComponent(agentId)}/sse${q ? `?${q}` : ""}`,
+        { headers: { "Accept": "text/event-stream" }, signal: options.signal }
+      );
+    } catch (e) {
+      if (!(e instanceof NotFoundError)) throw e;
+      if (!ROUTE_MISSING_404.test(e.message)) throw e;
+      this.agentSseSupported = false;
+      throw new UnsupportedVenueFeatureError("agent event stream");
+    }
+    for await (const evt of parseSSEStream(response, { signal: options.signal })) {
+      yield evt.json();
+    }
+  }
   /**
    * Page an agent's sessions directly from `g/<agentId>/sessions`.
    * This is a job-free Values read; session adapter-specific fields remain
@@ -1996,8 +2052,8 @@ var Job = class {
    * Stream server-sent events for this job.
    * @returns AsyncGenerator yielding SSEEvent objects
    */
-  async *stream() {
-    yield* this._jobs.stream(this.id);
+  async *stream(options) {
+    yield* this._jobs.stream(this.id, options);
   }
   /**
    * Whether the job is paused (PAUSED, INPUT_REQUIRED, or AUTH_REQUIRED)
@@ -2171,11 +2227,12 @@ var JobManager = class {
       throw error;
     }
   }
-  async *stream(jobId) {
+  async *stream(jobId, options) {
     const response = await venueStream(this.venue, `/api/v1/jobs/${jobId}/sse`, {
-      headers: { "Accept": "text/event-stream" }
+      headers: { "Accept": "text/event-stream" },
+      signal: options?.signal
     });
-    yield* parseSSEStream(response);
+    yield* parseSSEStream(response, { signal: options?.signal });
   }
 };
 
@@ -2849,6 +2906,68 @@ var DLFSManager = class {
   }
 };
 
+// src/UserManager.ts
+var UserManager = class {
+  constructor(venue) {
+    this.venue = venue;
+    // Whether this venue serves GET /api/v1/users — flipped on a route-missing
+    // 404 so a pre-#255 venue pays the probe once, not one failed GET per read.
+    this.usersSupported = true;
+  }
+  /** A job-free users GET that rejects when the endpoint is unavailable. */
+  async usersGet(path) {
+    if (!this.usersSupported) throw new UnsupportedVenueFeatureError("venue users");
+    try {
+      return await venueJson(this.venue, `/api/v1/users${path}`);
+    } catch (e) {
+      if (!(e instanceof NotFoundError)) throw e;
+      const routeMissing = path === "" || ROUTE_MISSING_404.test(e.message);
+      if (!routeMissing) throw e;
+      this.usersSupported = false;
+      throw new UnsupportedVenueFeatureError("venue users");
+    }
+  }
+  /**
+   * List registered venue users. **Job-free** on covia venues serving
+   * `GET /api/v1/users` (covia#255) — synchronous, no Job persisted.
+   * Operator-only: throws a `GridError` with `statusCode` 403 for a
+   * signed-in caller that is not the venue itself and holds no venue-issued
+   * delegation over `<venueDID>/users` — that is an expected, common
+   * outcome to branch on, not a bug.
+   */
+  async list() {
+    return this.usersGet("");
+  }
+  /**
+   * Get one registered user. The caller's own DID needs no operator
+   * authority; any other DID does (403 otherwise).
+   */
+  async info(did) {
+    return this.usersGet(`/${encodeURIComponent(did)}`);
+  }
+  /**
+   * List a venue-managed user's authenticators, active and revoked
+   * tombstones alike — revocation is a status transition in place, never a
+   * deletion. The caller's own DID needs no operator authority; any other
+   * DID does (403 otherwise).
+   */
+  async listAuthenticators(did) {
+    return this.usersGet(`/${encodeURIComponent(did)}/authentications`);
+  }
+  /**
+   * Revoke one of a venue-managed user's authenticators. A mutation, so —
+   * unlike the reads above — this goes through `operations.run` and mints a
+   * Job, matching every other write in this SDK (e.g. `SecretManager.set`).
+   */
+  async revokeAuthenticator(key, did, ucans) {
+    return this.venue.operations.run(
+      "v/ops/user/authentication-revoke",
+      { did, key },
+      { ucans }
+    );
+  }
+};
+
 // src/Agent.ts
 var Agent = class _Agent {
   constructor(id, venue) {
@@ -2898,6 +3017,10 @@ var Agent = class _Agent {
   async getSession(sessionId) {
     return this._agents.getSession(this.id, sessionId);
   }
+  /** Stream this agent's run-loop events. See `AgentManager.events`. */
+  async *events(options) {
+    yield* this._agents.events(this.id, options);
+  }
   /**
    * Fork this agent into a new agent.
    * @param agentId - ID for the new forked agent
@@ -3050,6 +3173,9 @@ var Venue = class _Venue {
   get dlfs() {
     return this._dlfs ?? (this._dlfs = new DLFSManager(this));
   }
+  get users() {
+    return this._users ?? (this._users = new UserManager(this));
+  }
   /**
    * Connect to a venue, validating it with `GET {base}/api/v1/status`. If the
    * venue is auth-gated (status answers 401/403 — public access disabled), the
@@ -3381,4 +3507,4 @@ function relayDelegation(privateKey, venueDID, lifetimeSeconds, caps = []) {
   (*! noble-ed25519 - MIT License (c) 2019 Paul Miller (paulmillr.com) *)
 */
 
-export { AdapterManager, Agent, AgentManager, AgentSessionNotFoundError, AgentStatus, Asset, AssetManager, AssetNotFoundError, Auth, BasicAuth, BearerAuth, ChatSession, CoviaConnectionError, CoviaError, CoviaTimeoutError, CredentialsHTTP, DLFSManager, DataAsset, Ed25519Auth, Grid, GridError, Job, JobFailedError, JobManager, JobNotFoundError, JobStatus, KeyPairAuth, MemoryManager, Namespace, NoAuth, NotFoundError, Operation, OperationManager, RateLimitError, RunStatus, SecretManager, SkillManager, UCANManager, UnsupportedVenueFeatureError, VENUE_RELAY, Venue, VenueIdentityChangedError, WorkspaceManager, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };
+export { AdapterManager, Agent, AgentManager, AgentSessionNotFoundError, AgentStatus, Asset, AssetManager, AssetNotFoundError, Auth, BasicAuth, BearerAuth, ChatSession, CoviaConnectionError, CoviaError, CoviaTimeoutError, CredentialsHTTP, DLFSManager, DataAsset, Ed25519Auth, Grid, GridError, Job, JobFailedError, JobManager, JobNotFoundError, JobStatus, KeyPairAuth, MemoryManager, Namespace, NoAuth, NotFoundError, Operation, OperationManager, RateLimitError, RunStatus, SecretManager, SkillManager, UCANManager, UnsupportedVenueFeatureError, UserManager, VENUE_RELAY, Venue, VenueIdentityChangedError, WorkspaceManager, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@covia/covia-sdk",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Typescript library for covia-ai",
   "packageManager": "pnpm@11.9.0",
   "main": "./dist/index.js",