@primusclaw/personal-agent 0.0.0-stage → 0.1.1

package/dist/types/ports/claw/assistant.d.ts

@@ -0,0 +1,55 @@
+import type { JsonObject } from "../../json.js";
+import type { ClawCredential } from "../../claw/credential.js";
+import type { PullRef, ReviewStart } from "../../claw/model.js";
+/** One pull request to review and the first message its session gets ("" Claw's own). */
+export interface ReviewTarget {
+    readonly pull: PullRef;
+    readonly message: string;
+}
+/** A request for reviews (`POST /v1/assistant/reviews`); all of them start or none does. */
+export interface StartReviews {
+    /** The requester's own linked key, as the model key (not sent for a review asked of someone else). */
+    readonly modelKey: string;
+    readonly prs: readonly ReviewTarget[];
+    readonly actingAs: string;
+    readonly actingAsName: string;
+    readonly reviewOnly: boolean;
+    readonly model: string;
+    /** A review asked of someone else: that person's exchanged token and own linked key. */
+    readonly actingToken?: string;
+    readonly actingKey?: string;
+    /** The asker's own words, quoted to the reviewer as untrusted. */
+    readonly requesterNote?: string;
+    /** The handoff the assistant gave back, whose record says what the review may do. */
+    readonly handoffId?: string;
+}
+/** Options of a message to the assistant. */
+export interface AssistantMessageOptions {
+    readonly modelKey?: string;
+    /** The chat's `channel_context`. */
+    readonly context?: Readonly<JsonObject>;
+    /** The plugin id the web client names (`pluginId`). */
+    readonly plugin?: number;
+}
+/** The person's assistant in Claw and what it does for them (`/v1/assistant/*`). */
+export interface ClawAssistantPort {
+    /** The key owner's assistant session, made on first use. ClawError(404): the assistant is off on this Claw. */
+    session(key: ClawCredential): Promise<{
+        sessionId: string;
+        created: boolean;
+    }>;
+    /** Says `text` to the assistant as typed; its message id, or null when queued. The answer comes back as an event. */
+    send(key: ClawCredential, sessionId: string, text: string, options?: AssistantMessageOptions): Promise<string | null>;
+    /** The caller's brief, put together now: `{date, lang, sections, needs_you, text}`. */
+    brief(key: ClawCredential, lang: string, timezone: string): Promise<JsonObject>;
+    /** The person's answer to a held write the assistant put to them (`allow` or `deny`); exchanged token only. */
+    decideConfirmation(token: ClawCredential, confirmationId: string, decision: string): Promise<JsonObject>;
+    /** Reviews as `actingAs`, each a work item. ReviewsRefused: none started. ClawError(404): a Claw without the route. */
+    startReviews(token: ClawCredential, request: StartReviews): Promise<ReviewStart[]>;
+    /** Makes the key owner's watcher of `scope` observe it. */
+    observeScope(key: ClawCredential, scope: string): Promise<JsonObject>;
+    /** Hands one message of an observed place to the watcher. ClawError(429 observe_backlog): it is behind. */
+    observe(key: ClawCredential, scope: string, content: string, messageId: string): Promise<JsonObject>;
+    /** What the watcher of `scope` would have done, newest first ([] for a scope never watched). */
+    observations(key: ClawCredential, scope: string, limit?: number): Promise<JsonObject[]>;
+}

package/dist/types/ports/claw/index.d.ts

@@ -0,0 +1,28 @@
+import type { ClawAssistantPort } from "./assistant.js";
+import type { ClawRemoteAgentsPort } from "./remote-agents.js";
+import type { ClawSessionsPort } from "./sessions.js";
+import type { ClawMergeConfirmationsPort, ClawNotificationsPort, ClawSettingsPort, ClawTriggersPort } from "./settings.js";
+import type { ClawWorkItemsPort } from "./work-items.js";
+export type * from "./assistant.js";
+export type * from "./remote-agents.js";
+export type * from "./sessions.js";
+export type * from "./settings.js";
+export type * from "./work-items.js";
+/**
+ * Claw's public HTTP API, always called as one person with that person's own credential (a per-call argument, never
+ * kept). Grouped by resource. Errors: ClawError (Claw answered with an error), ReviewsRefused, ReplayRefused,
+ * ClawAnswerInvalid (an answer this client does not understand), CredentialMisuse (refused before sending),
+ * ClawUnreachable. An id that could change which endpoint a request reaches is refused as ClawError(404).
+ */
+export interface ClawPort {
+    /** The address Claw's API is reached at. */
+    readonly baseUrl: string;
+    readonly sessions: ClawSessionsPort;
+    readonly workItems: ClawWorkItemsPort;
+    readonly assistant: ClawAssistantPort;
+    readonly settings: ClawSettingsPort;
+    readonly notifications: ClawNotificationsPort;
+    readonly triggers: ClawTriggersPort;
+    readonly mergeConfirmations: ClawMergeConfirmationsPort;
+    readonly remoteAgents: ClawRemoteAgentsPort;
+}

package/dist/types/ports/claw/remote-agents.d.ts

@@ -0,0 +1,53 @@
+import type { JsonObject } from "../../json.js";
+import type { RemoteHidden } from "../../protocol.js";
+import type { ClawCredential } from "../../claw/credential.js";
+import type { SseEvent } from "../../claw/model.js";
+import type { RemoteConnector, RemoteEventRow, RemotePairing, RemoteSession, RemoteSetup } from "../../claw/remote.js";
+/** What a remote session starts with. */
+export interface NewRemoteSession {
+    readonly connectorId: string;
+    readonly agentId: string;
+    readonly cwd: string;
+    /** The permission mode to start in (absent: the agent's own). */
+    readonly mode?: string;
+    /** An existing conversation the agent offered to take over, passed on unread. */
+    readonly resumeRef?: string;
+    /** The person confirmed the terminal holding that conversation is ended first (only with `resumeRef`). */
+    readonly takeover?: boolean;
+}
+/**
+ * Agents on the user's own machines, the user side (`/v1/remote-agents/*`). Every call names this client in Claw's
+ * audit trail (`X-Claw-Client`).
+ */
+export interface ClawRemoteAgentsPort {
+    /** How to connect a machine: the connector's package and the exact commands. */
+    setup(key: ClawCredential): Promise<RemoteSetup>;
+    /**
+     * The caller's connectors, each with `online` and its `agents`. The conversations the caller hid are left out of each
+     * agent's `capabilities.resumable` and counted in `capabilities.hidden_count`; `includeHidden` lists them too, marked
+     * `hidden: true` (`?hidden=include`).
+     */
+    connectors(key: ClawCredential, options?: {
+        includeHidden?: boolean;
+    }): Promise<RemoteConnector[]>;
+    /**
+     * Hides conversations (1-50 refs) of one of the caller's machines from their lists, or (`hidden` false) shows them
+     * again; nothing on the machine changes. ClawError(404): not the caller's machine, or revoked; 400 for refs Claw does
+     * not take.
+     */
+    hide(key: ClawCredential, connectorId: string, refs: readonly string[], hidden: boolean): Promise<RemoteHidden>;
+    /** A one-time pairing code inside the command line that uses it. */
+    pair(key: ClawCredential): Promise<RemotePairing>;
+    revoke(key: ClawCredential, connectorId: string): Promise<void>;
+    createSession(key: ClawCredential, session: NewRemoteSession): Promise<RemoteSession>;
+    sessions(key: ClawCredential): Promise<RemoteSession[]>;
+    session(key: ClawCredential, sessionId: string): Promise<RemoteSession>;
+    /** One command (`prompt`, `cancel`, `set_mode`, `resume`, `close`); a retry with the same key queues one command. */
+    command(key: ClawCredential, sessionId: string, body: Readonly<JsonObject>, idempotencyKey?: string): Promise<JsonObject>;
+    /** Answers a permission request with an option id the agent itself offered. */
+    decide(key: ClawCredential, sessionId: string, actionId: string, optionId: string): Promise<JsonObject>;
+    /** A page of stored events `{id, seq, type, ts, data}`, oldest first, after `after`. */
+    events(key: ClawCredential, sessionId: string, after?: string, limit?: number): Promise<RemoteEventRow[]>;
+    /** Stored events after `after`, a `historyComplete` marker, then live events. */
+    stream(key: ClawCredential, sessionId: string, after?: string, signal?: AbortSignal): AsyncIterable<SseEvent>;
+}

package/dist/types/ports/claw/sessions.d.ts

@@ -0,0 +1,105 @@
+import type { JsonObject } from "../../json.js";
+import type { ClawCredential } from "../../claw/credential.js";
+import type { PullRef, SseEvent } from "../../claw/model.js";
+/** What a new session is made with (`POST /v1/sessions`). */
+export interface NewSession {
+    /** The first message; also the session's name (its first 50 characters). */
+    readonly text: string;
+    readonly idempotencyKey: string;
+    /** The git repository the session is bound to (`config.repo`); `branch` "" takes the remote's default. */
+    readonly repo?: {
+        readonly url: string;
+        readonly branch: string;
+    };
+    /** The user the session's GitHub review tools act for (`config.acting_as`); needs an exchanged token, never an `ak-` key. */
+    readonly actingAs?: string;
+    /** The one pull request such a session's review tools may touch (`config.review_target`). */
+    readonly reviewTarget?: PullRef;
+    /** The requester's own linked key, sent as `x-api-key` next to an exchanged token (never next to an `ak-` key). */
+    readonly modelKey?: string;
+    /** The model its turns ask for; "" leaves the configured default (or Claw's). */
+    readonly model?: string;
+    /** `config.review_only`: Claw refuses a merge in that session. */
+    readonly reviewOnly?: boolean;
+    /** false: the session is made with no message (`text` is only its name) and `messageId` is "". Default true. */
+    readonly withMessage?: boolean;
+    /** Other people read the session (a group chat): `config.memory = "off"`. */
+    readonly shared?: boolean;
+}
+/** One file put into a session's workspace. */
+export interface UploadFile {
+    readonly name: string;
+    readonly content: Uint8Array;
+    readonly mediaType: string;
+}
+/** Options of a message into a session. */
+export interface SendOptions {
+    /** See `NewSession.modelKey`. */
+    readonly modelKey?: string;
+    /** The session acts as a user: the message goes as the text alone, without plugin or appended rules. */
+    readonly acting?: boolean;
+}
+/**
+ * Claw sessions: making them, writing into them and reading them back
+ * (`/v1/sessions/*`, `/v1/chat/sessions/:id/messages`).
+ */
+export interface ClawSessionsPort {
+    /** Throws ClawError(401) when Claw does not accept the key. */
+    checkKey(key: ClawCredential): Promise<void>;
+    /** A new session; its first message's id ("" when made without one). */
+    create(key: ClawCredential, session: NewSession): Promise<{
+        sessionId: string;
+        messageId: string;
+    }>;
+    /**
+     * Puts files in the session's workspace under `.uploads/<folder>/` (kept 7 days): the paths the agent finds them at,
+     * and the names Claw did not take.
+     */
+    uploadFiles(key: ClawCredential, sessionId: string, folder: string, files: readonly UploadFile[]): Promise<{
+        paths: string[];
+        refused: string[];
+    }>;
+    /** Pins an existing session to `model` (`PATCH /v1/sessions/:id`). */
+    setModel(key: ClawCredential, sessionId: string, model: string): Promise<void>;
+    /** Sends `text`; its message id, or null when Claw queued it behind a turn still running. */
+    sendMessage(key: ClawCredential, sessionId: string, text: string, options?: SendOptions): Promise<string | null>;
+    /** Whether a turn holds the session, and that turn's message id when Claw says it. */
+    turn(key: ClawCredential, sessionId: string): Promise<{
+        running: boolean;
+        messageId: string | null;
+    }>;
+    /**
+     * The session's stored events as rows `{event_id, event_type, data, created_at}`, oldest first (`?mode=replay`).
+     * `tail`: only the last `tail`. `maxBytes`: a larger reply is refused (ReplayRefused) before it is held whole.
+     */
+    events(key: ClawCredential, sessionId: string, options?: {
+        tail?: number;
+        maxBytes?: number;
+    }): Promise<JsonObject[]>;
+    /** The id of the session's newest stored event (null: none), read bounded. */
+    lastEventId(key: ClawCredential, sessionId: string): Promise<string | null>;
+    /**
+     * What the session changed in its sandbox (`GET /v1/sessions/:id/changes`), as Claw answers it; the whole call is
+     * bounded by `timeoutMs` (ClawUnreachable "timeout") and a reply larger than the limit is refused (ReplayRefused).
+     */
+    changes(key: ClawCredential, sessionId: string, timeoutMs: number): Promise<unknown>;
+    /** Where the user downloads a file the agent delivered (null when Claw is not reached over https). */
+    deliveryLink(sessionId: string, deliveryId: string): string | null;
+    /** Ends the running turn. */
+    interrupt(key: ClawCredential, sessionId: string): Promise<void>;
+    /** The answer to an approval card of the session's model (`messageType: decision`). */
+    decide(key: ClawCredential, sessionId: string, toolUseId: string, action: string, options?: {
+        acting?: boolean;
+    }): Promise<void>;
+    /** The answer to a question card (`messageType: answer`): {question id: answer} and the ids left blank. */
+    answer(key: ClawCredential, sessionId: string, toolUseId: string, answers: Readonly<Record<string, string>>, skipped: readonly string[], options?: {
+        acting?: boolean;
+    }): Promise<void>;
+    /** The key owner's thumbs up or down on one answer of their session (a second vote replaces the first). */
+    vote(key: ClawCredential, sessionId: string, messageId: string, vote: "up" | "down", reason?: string): Promise<void>;
+    /**
+     * The session's SSE stream: history first (ended by `historyComplete`), then live events. `onOpen` is called once Claw has
+     * answered the request (its status), before any event: from then on, what the session says reaches this stream.
+     */
+    stream(key: ClawCredential, sessionId: string, after?: string, signal?: AbortSignal, onOpen?: () => void): AsyncIterable<SseEvent>;
+}

package/dist/types/ports/claw/settings.d.ts

@@ -0,0 +1,62 @@
+import type { JsonObject } from "../../json.js";
+import type { ClawCredential } from "../../claw/credential.js";
+import type { GithubConnection, MemoryState } from "../../claw/model.js";
+import type { NotificationSubscription } from "../../protocol.js";
+/** The person's own settings in Claw: memory, models, the assistant's model choice, GitHub. */
+export interface ClawSettingsPort {
+    /** Memory on or off, whether Claw has it, and up to `limit` remembered items (profile entries left out). */
+    memory(key: ClawCredential, limit?: number): Promise<MemoryState>;
+    /** Turns memory on or off; what Claw answers. */
+    setMemory(key: ClawCredential, enabled: boolean): Promise<{
+        enabled: boolean;
+        available: boolean;
+    }>;
+    /** The models the key's owner may use. ClawError when Claw cannot say (never an empty list for that). */
+    models(key: ClawCredential): Promise<string[]>;
+    /** The assistant's model settings, or null for a Claw without model choice (404). */
+    assistantSettings(token: ClawCredential): Promise<JsonObject | null>;
+    /** `high_risk_confirm` or `fully_auto` ("" not said). */
+    reviewMode(token: ClawCredential): Promise<string>;
+    setReviewMode(token: ClawCredential, mode: string): Promise<void>;
+    /** Which GitHub token Claw would use for them, or null for a Claw without the answer (404). */
+    githubConnection(token: ClawCredential): Promise<GithubConnection | null>;
+}
+/** A notification subscription as Claw lists it; the signing secret only on the answer that made it. */
+export type ClawSubscription = Partial<NotificationSubscription> & {
+    readonly secret?: string;
+} & JsonObject;
+/** Notification subscriptions (`/v1/notification-subscriptions`). ClawError(404): notifications are off on Claw. */
+export interface ClawNotificationsPort {
+    list(key: ClawCredential): Promise<ClawSubscription[]>;
+    /** Subscribes the key's owner at `url`; the reply carries the signing secret, once. Empty lists: Claw's defaults. */
+    create(key: ClawCredential, url: string, eventTypes?: readonly string[], sources?: readonly string[]): Promise<ClawSubscription>;
+    /** Changes which events (and, given, which sources) a subscription gets; `enable` turns it on again. */
+    updateTypes(key: ClawCredential, subscriptionId: string, eventTypes: readonly string[], options?: {
+        enable?: boolean;
+        sources?: readonly string[];
+    }): Promise<ClawSubscription>;
+    delete(key: ClawCredential, subscriptionId: string): Promise<void>;
+}
+/** What a scheduled trigger is made or changed with. `action` "brief": the assistant says the brief, no run. */
+export interface TriggerInput {
+    readonly name: string;
+    readonly prompt: string;
+    readonly schedule: string;
+    readonly timezone: string;
+    readonly action?: string;
+}
+/** The caller's own scheduled triggers (`/v1/triggers`), passed on as Claw answers them. */
+export interface ClawTriggersPort {
+    list(key: ClawCredential): Promise<JsonObject[]>;
+    create(key: ClawCredential, trigger: TriggerInput): Promise<JsonObject>;
+    /** `action` is not sent on a change. */
+    update(key: ClawCredential, triggerId: string, trigger: TriggerInput): Promise<JsonObject>;
+    delete(key: ClawCredential, triggerId: string): Promise<void>;
+}
+/** Held high-risk merges of GitHub reviews (`/v1/github-review/confirmations`). */
+export interface ClawMergeConfirmationsPort {
+    /** The merges this session waits on someone to confirm. ClawError(404): the review feature is off. */
+    pending(key: ClawCredential, sessionId: string): Promise<JsonObject[]>;
+    /** The answer of the user the review acts for (`allow` | `deny`); exchanged token only. `{status, reason, merge_sha}`. */
+    decide(token: ClawCredential, confirmationId: string, decision: string): Promise<JsonObject>;
+}

package/dist/types/ports/claw/work-items.d.ts

@@ -0,0 +1,32 @@
+import type { JsonObject } from "../../json.js";
+import type { ClawCredential } from "../../claw/credential.js";
+import type { ReviewAskedOfOther, Decision, AskerView, WorkItem } from "../../claw/model.js";
+import type { BoardState } from "../../protocol.js";
+/** The assistant's work items, the board (`/v1/work-items/*`). */
+export interface ClawWorkItemsPort {
+    /** The caller's board, newest first; `state` narrows it (done: the last 7 days). */
+    list(key: ClawCredential, state?: BoardState): Promise<WorkItem[]>;
+    /** The reviews the caller asked of others, newest first ([] from a Claw without the route). */
+    askedOfOthers(key: ClawCredential): Promise<ReviewAskedOfOther[]>;
+    /** One of the caller's items as it is now. ClawError(404): not theirs, or gone. */
+    get(key: ClawCredential, itemId: string): Promise<WorkItem>;
+    /** What the asker of a review someone else runs may know of it now. */
+    requesterView(key: ClawCredential, itemId: string): Promise<AskerView>;
+    /** Accepts result `version` and only that one; a 409 comes back as a Decision with the item as it is now. */
+    accept(key: ClawCredential, itemId: string, version: number): Promise<Decision>;
+    /** Runs a task that failed or was stopped again. */
+    retry(key: ClawCredential, itemId: string): Promise<Decision>;
+    /** Stops the item and its worker. */
+    stop(key: ClawCredential, itemId: string): Promise<Decision>;
+    /** The item, and the pull requests its worker reported as its result (newest first, each once). */
+    pulls(key: ClawCredential, itemId: string): Promise<{
+        item: WorkItem;
+        pulls: string[];
+    }>;
+    /** The item watches `pull` on GitHub; `reply` needs the person's exchanged token. */
+    watchPull(token: ClawCredential, itemId: string, pull: string, reply?: boolean): Promise<JsonObject>;
+    /** The pull requests the item watches, and watched: each `{sub_id, pr, url, reply_allowed, state, ...}`. */
+    watches(key: ClawCredential, itemId: string): Promise<JsonObject[]>;
+    /** The item stops watching one pull request. */
+    unwatchPull(key: ClawCredential, itemId: string, subId: string): Promise<JsonObject>;
+}

package/dist/types/ports/clock.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Time, injected. Nothing in core reads `Date.now()`, `performance.now()` or calls `setTimeout` itself: tests drive a
+ * fake clock (`test-support/clock.ts`), the runtime gives the system's (`@primusclaw/personal-agent-runtime`).
+ */
+export interface Clock {
+    /** Wall-clock time, milliseconds since the Unix epoch (what is stored and shown; it can jump). */
+    epochMs(): number;
+    /** A monotonic reading in milliseconds, for durations and deadlines only (never stored; its origin is arbitrary). */
+    monotonicMs(): number;
+    /**
+     * Resolves after `ms` milliseconds of this clock. With `signal`, rejects with the signal's reason as soon as it is
+     * aborted (an abort that happened before the call rejects at once).
+     */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+/** Wall-clock seconds since the epoch, as a float: the unit the stored timestamps use (`created_at REAL`). */
+export declare function epochSeconds(clock: Clock): number;

package/dist/types/ports/crypto.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Hashing and message authentication for the domain (ids derived from text, signed callbacks). Encryption at rest is
+ * the store's own business and is not offered here.
+ */
+export type Bytes = string | Uint8Array;
+export interface Crypto {
+    /** Hex SHA-256 of `data` (a string is taken as UTF-8). */
+    sha256Hex(data: Bytes): string;
+    /** Hex SHA-1, for ids that are already SHA-1 derived elsewhere; never for security. */
+    sha1Hex(data: Bytes): string;
+    /** Hex HMAC-SHA256 of `data` under `key`. */
+    hmacSha256Hex(key: Bytes, data: Bytes): string;
+    /** Constant-time equality; false for different lengths. */
+    timingSafeEqual(a: Bytes, b: Bytes): boolean;
+}

package/dist/types/ports/github.d.ts

@@ -0,0 +1,97 @@
+/**
+ * What the review delegation needs from GitHub and from the identity service's GitHub credentials, as ports. The runtime
+ * implements them over HTTP (`runtime/src/github/`); tests use fakes. No port ever returns or logs a GitHub token except
+ * `DeviceFlow.waitForToken`, whose token goes straight to `GithubCredentials.bind`.
+ */
+import type { NotBound } from "../plugins/token-exchange.js";
+import type { Result } from "../result.js";
+import type { PullRef } from "../claw/model.js";
+/** The GitHub device flow ended without a token: 'unavailable' (GitHub did not answer sensibly), 'expired' (the code ran
+ * out unused) or 'denied' (the person said no). Nothing but the reason is kept (no body, no code, no token). */
+export interface DeviceFlowFailed {
+    readonly kind: "device_flow_failed";
+    readonly reason: "unavailable" | "expired" | "denied";
+}
+/** The wait was given up on (the person sent `/github unbind` meanwhile). */
+export interface DeviceFlowCancelled {
+    readonly kind: "device_flow_cancelled";
+}
+export interface DeviceCode {
+    /** What the worker polls with; never shown. */
+    readonly deviceCode: string;
+    /** What the person types. */
+    readonly userCode: string;
+    readonly verificationUri: string;
+    readonly expiresIn: number;
+    readonly interval: number;
+}
+/** RFC 8628 against github.com with a public client; the scope asked for is always `repo`. */
+export interface DeviceFlow {
+    start(): Promise<Result<DeviceCode, DeviceFlowFailed>>;
+    /** Polls until the person approves: the token, or why not. An aborted `signal` ends the wait as `cancelled`. */
+    waitForToken(code: DeviceCode, signal?: AbortSignal): Promise<Result<string, DeviceFlowFailed | DeviceFlowCancelled>>;
+}
+/**
+ * The identity service refused or could not be asked. `status` is the HTTP status (0: no answer) and `code` its OAuth error
+ * code; nothing else of the answer is kept.
+ */
+export interface CredentialRefused {
+    readonly kind: "credential_refused";
+    readonly status: number;
+    readonly code: string;
+}
+/** `not_bound`: the identity service has no binding for this person; only they can make one, by connecting their account. */
+export type CredentialFailure = NotBound | CredentialRefused;
+export declare function credentialRefused(status: number, code?: string): CredentialRefused;
+/** How a refusal is logged: status and code only. */
+export declare function describeRefusal(refused: CredentialRefused): string;
+export interface GithubState {
+    readonly userId: string;
+    readonly bound: boolean;
+    readonly login: string;
+    readonly scopes: readonly string[];
+    readonly expiresAt: string;
+    readonly expired: boolean;
+    readonly delegation: boolean;
+    readonly lastUsedAt: string;
+}
+export declare function usable(state: GithubState): boolean;
+export declare const SCOPE = "repo";
+export declare const NARROW_SCOPE = "public_repo";
+/** A binding whose permissions do not reach private and internal repositories (`public_repo` only, or none known). */
+export declare function needsWiderScope(scopes: readonly string[]): boolean;
+/** The identity service's `/oauth/external-credentials` calls for a person (by their directory id). */
+export interface GithubCredentials {
+    status(userId: string): Promise<Result<GithubState, CredentialFailure>>;
+    bind(userId: string, token: string): Promise<Result<GithubState, CredentialFailure>>;
+    unbind(userId: string): Promise<Result<boolean, CredentialFailure>>;
+    setDelegation(userId: string, enabled: boolean): Promise<Result<GithubState, CredentialFailure>>;
+}
+/** Who wrote a pull request, and other public facts, read with no credential. Any failure reads as "not known". */
+export interface PullReader {
+    /** The repository's own "owner/name" when GitHub has it public, '' when it does not (404), undefined when it could not be read. */
+    repo(owner: string, name: string): Promise<string | undefined>;
+    /** The branch the pull request goes into ('' when not read). */
+    base(pull: PullRef): Promise<string>;
+    /** Who wrote it (undefined: not read) and its title ('' not read). */
+    read(pull: PullRef): Promise<{
+        readonly author: string | undefined;
+        readonly title: string;
+    }>;
+}
+/** One mention as the model is shown it: its marker in the text, its id, and its display name. */
+export interface ListedMention {
+    readonly marker: string;
+    readonly id: string;
+    readonly name: string;
+}
+/**
+ * One small model call that says what a message asks for, with the asker's own key. undefined for anything but an answer in
+ * time (no model, the gateway refused or was slow): the rules read it instead. `{ intent: null }` when it answered something
+ * that is not a JSON object.
+ */
+export interface IntentReader {
+    read(key: string, text: string, mentions: readonly ListedMention[]): Promise<Record<string, unknown> | undefined>;
+    readMode(key: string, text: string): Promise<Record<string, unknown> | undefined>;
+    readAnswer(key: string, text: string, pending: readonly Readonly<Record<string, string>>[]): Promise<Record<string, unknown> | undefined>;
+}

package/dist/types/ports/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Every port core talks to the outside through. Ownership while the port is written (the Python module it follows):
+ *   W0: Surface (messenger.py, activity.py), Clock, Random, Logger.
+ *   W1: StorePort and the repositories (store.py), Crypto (store.py Fernet, link-code HMAC).
+ *   W2: ClawPort (claw.py), Metrics (metrics.py), SecretSource (secret_source.py), Config (config.py).
+ * Implementations live in the runtime package (Node) or a channel package; tests use `test-support/`.
+ */
+export * from "./clock.js";
+export * from "./logger.js";
+export * from "./random.js";
+export * from "./surface.js";
+export * from "./claw/index.js";
+export * from "./metrics.js";
+export * from "./secret-source.js";
+export * from "./request-scope.js";
+export * from "./routing.js";
+export * from "./turn-cards.js";
+export * from "./github.js";

package/dist/types/ports/logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Structured logging, injected. A message is a fixed sentence; what varies goes in `fields`.
+ *
+ * What a log line never carries: what a person wrote, what an agent answered, a token, a key, a response body, a file
+ * name or its bytes. Counts, ids, statuses, durations and error kinds (`errorName`) are what is logged.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogValue = string | number | boolean | null | undefined;
+export type LogFields = Readonly<Record<string, LogValue>>;
+export interface Logger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    /** A logger whose every line also carries `fields` (a module name, the conversation a task works for). */
+    child(fields: LogFields): Logger;
+}
+/** A logger that drops everything: the default where a caller passes none. */
+export declare const silentLogger: Logger;

package/dist/types/ports/metrics.d.ts

@@ -0,0 +1,21 @@
+import type { SecurityEventRecord } from "../observability/security-events.js";
+/**
+ * The counters behind the operator's alerts. Every label value comes from a closed list
+ * (`../observability/metrics-catalog.ts`), so no label ever names a person, a conversation or anything a person chose;
+ * a value outside its list is counted under the list's catch-all or not at all. The runtime serves them in the
+ * Prometheus text format (`GET /metrics` on its own port); tests use a recording fake.
+ */
+export interface MetricsPort {
+    /** One event from Claw reached the chat: `handleSeconds` after it was received, `sinceOccurredSeconds` after Claw says it happened (null: not said). */
+    eventDelivered(eventType: string, handleSeconds: number, sinceOccurredSeconds: number | null): void;
+    /** One security event as `securityEvent` logged it. */
+    securityEvent(record: SecurityEventRecord): void;
+    /** One inbound message handled: how long it waited in the queue (null: unknown), how long handling took, whether it succeeded. */
+    processed(lagMs: number | null, handleMs: number, ok: boolean): void;
+    /** A message or task refused by a per-user limit (`user_limit` | `concurrency_limit`). */
+    limited(reason: string): void;
+    /** `count` files a person sent did not reach Claw on `path` (assistant | session | remote_agent | review | unreadable). */
+    filesDropped(path: string, count?: number): void;
+}
+/** Metrics that go nowhere: the default where a caller passes none. */
+export declare const noMetrics: MetricsPort;

package/dist/types/ports/random.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Randomness, injected: ids, nonces and jitter. The runtime's implementation is cryptographically strong
+ * (`node:crypto`), so a value from here may be used where it must not be guessed (a link code, an ack id).
+ * Tests use a seeded one (`test-support/random.ts`) so their output is the same on every run.
+ */
+export interface Random {
+    /** `n` random bytes. */
+    bytes(n: number): Uint8Array;
+    /** A random id: 32 lowercase hex characters (the shape of Python's `uuid.uuid4().hex`). */
+    hexId(): string;
+    /** A uniformly distributed integer in [0, maxExclusive). */
+    int(maxExclusive: number): number;
+    /** A float in [0, 1), for jitter only. */
+    fraction(): number;
+}

package/dist/types/ports/request-scope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What the worker is handling right now: the inbound activity a piece of work was started by, so that what runs on its
+ * behalf (an answer's language, an audit record, a log line kept for /feedback) knows it without every call passing it
+ * on. The router enters it once per inbound event, after the duplicate check and before routing (Python agent.py
+ * `Agent.handle`: LOG_SCOPE, CLIENT_LOCALE and ACTIVITY_ID set around `_route`). Work started inside keeps it after the
+ * router has returned, as an asyncio task copies its context; work started outside any event (a timer, a pushed
+ * notification, start-up recovery) reads none.
+ */
+/** The inbound event's context (Python: CLIENT_LOCALE, ACTIVITY_ID, and LOG_SCOPE's aad id and conversation id). */
+export interface RequestContext {
+    /** The client's locale as the channel said it ("" when it did not). */
+    readonly clientLocale: string;
+    /** The inbound activity's id ("" when it has none). */
+    readonly activityId: string;
+    /** The sender's id. */
+    readonly userId: string;
+    /** The conversation's id. */
+    readonly conversationId: string;
+}
+export interface RequestScope {
+    /** Runs `fn` inside `context` (and what it starts, for as long as that runs); the outer context is back after it. */
+    run<T>(context: RequestContext, fn: () => T): T;
+    /** The context of the event being handled; undefined outside any. */
+    current(): RequestContext | undefined;
+}
+/** A scope that keeps nothing: `run` only runs, `current` is always undefined (what a worker without one reads). */
+export declare const noRequestScope: RequestScope;
+/** The client locale of the event being handled ("" outside any: Python CLIENT_LOCALE's default). */
+export declare function clientLocaleOf(scope: RequestScope): string;
+/** The id of the activity being handled ("" outside any: Python ACTIVITY_ID's default, None). */
+export declare function activityIdOf(scope: RequestScope): string;