@primusclaw/personal-agent-runtime 0.0.0-stage → 0.1.0

package/dist/sqlite/schema.sql

@@ -0,0 +1,122 @@
+
+CREATE TABLE IF NOT EXISTS links (
+  aad_id TEXT PRIMARY KEY, name TEXT NOT NULL, key_enc BLOB NOT NULL, created_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS pending_keys (
+  code_hash TEXT PRIMARY KEY, key_enc BLOB NOT NULL, expires_at REAL NOT NULL,
+  used INTEGER NOT NULL DEFAULT 0);
+CREATE TABLE IF NOT EXISTS link_attempts (
+  aad_id TEXT NOT NULL, at REAL NOT NULL);
+DROP TABLE IF EXISTS link_codes;
+CREATE TABLE IF NOT EXISTS sessions (
+  aad_id TEXT NOT NULL, scope TEXT NOT NULL DEFAULT '', session_id TEXT NOT NULL, updated_at REAL NOT NULL,
+  plugin_id TEXT NOT NULL DEFAULT '', model TEXT NOT NULL DEFAULT '', shared INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (aad_id, scope));
+CREATE TABLE IF NOT EXISTS processed (
+  activity_id TEXT PRIMARY KEY, at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS event_claims (
+  event_key TEXT PRIMARY KEY, state TEXT NOT NULL, holder TEXT NOT NULL, until REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS conversation_refs (
+  aad_id TEXT PRIMARY KEY, reference_json TEXT NOT NULL, updated_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS user_prefs (
+  aad_id TEXT PRIMARY KEY, timezone TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS held_events (
+  event_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, event_json TEXT NOT NULL, held_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS approvals (
+  session_id TEXT NOT NULL, tool_use_id TEXT NOT NULL, aad_id TEXT NOT NULL, tool TEXT NOT NULL,
+  expires_at REAL NOT NULL, state TEXT NOT NULL DEFAULT 'pending', created_at REAL NOT NULL,
+  card_sent INTEGER NOT NULL DEFAULT 1, card_json TEXT,
+  PRIMARY KEY (session_id, tool_use_id));
+CREATE TABLE IF NOT EXISTS notify_subs (
+  aad_id TEXT PRIMARY KEY, route TEXT NOT NULL UNIQUE, subscription_id TEXT NOT NULL,
+  secret_enc BLOB NOT NULL, created_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS notify_sub_attempts (
+  aad_id TEXT PRIMARY KEY, at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS turn_answers (
+  session_id TEXT PRIMARY KEY, started_at REAL NOT NULL, delivered_at REAL, boot_id TEXT NOT NULL DEFAULT '',
+  prompt TEXT NOT NULL DEFAULT '', ended INTEGER NOT NULL DEFAULT 0, message_id TEXT NOT NULL DEFAULT '',
+  turn_id TEXT NOT NULL DEFAULT '');
+CREATE TABLE IF NOT EXISTS answered_messages (
+  session_id TEXT NOT NULL, message_id TEXT NOT NULL, delivered_at REAL NOT NULL, PRIMARY KEY (session_id, message_id));
+CREATE TABLE IF NOT EXISTS feedback_reports (
+  id INTEGER PRIMARY KEY AUTOINCREMENT, aad_id TEXT NOT NULL, scope TEXT NOT NULL DEFAULT '',
+  session_id TEXT NOT NULL DEFAULT '', text TEXT NOT NULL, scene TEXT NOT NULL, created_at REAL NOT NULL,
+  state TEXT NOT NULL DEFAULT 'pending', issue_number INTEGER, issue_url TEXT NOT NULL DEFAULT '',
+  as_comment INTEGER NOT NULL DEFAULT 0, attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at REAL NOT NULL DEFAULT 0, last_error TEXT NOT NULL DEFAULT '',
+  reporter_name TEXT NOT NULL DEFAULT '', reporter_email TEXT NOT NULL DEFAULT '');
+CREATE INDEX IF NOT EXISTS feedback_reports_by_user ON feedback_reports (aad_id, scope, session_id, created_at);
+CREATE TABLE IF NOT EXISTS feedback_asks (
+  aad_id TEXT NOT NULL, scope TEXT NOT NULL DEFAULT '', asked_at REAL NOT NULL, PRIMARY KEY (aad_id, scope));
+CREATE TABLE IF NOT EXISTS feedback_offers (
+  offer_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, issue_number INTEGER NOT NULL, session_id TEXT NOT NULL,
+  turn_id TEXT NOT NULL DEFAULT '', created_at REAL NOT NULL, state TEXT NOT NULL DEFAULT 'open');
+CREATE TABLE IF NOT EXISTS feedback_prompts (
+  prompt_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, scope TEXT NOT NULL DEFAULT '', created_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS onboarding_cards (
+  prompt_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, scope TEXT NOT NULL, teams_id TEXT NOT NULL DEFAULT '',
+  name TEXT NOT NULL DEFAULT '', created_at REAL NOT NULL);
+CREATE INDEX IF NOT EXISTS onboarding_cards_by_user ON onboarding_cards (aad_id, scope, created_at);
+CREATE TABLE IF NOT EXISTS onboarding_dms (
+  aad_id TEXT PRIMARY KEY, at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS pending_requests (
+  aad_id TEXT PRIMARY KEY, scope TEXT NOT NULL, message_id TEXT NOT NULL, text TEXT NOT NULL,
+  reference_json TEXT NOT NULL, created_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS github_confirmations (
+  confirmation_id TEXT PRIMARY KEY, session_id TEXT NOT NULL, actor_aad TEXT NOT NULL, requester_aad TEXT NOT NULL,
+  repo TEXT NOT NULL, pr INTEGER NOT NULL, reference_json TEXT NOT NULL, expires_at REAL NOT NULL,
+  state TEXT NOT NULL DEFAULT 'pending', created_at REAL NOT NULL,
+  kind TEXT NOT NULL DEFAULT 'merge', event TEXT NOT NULL DEFAULT '');
+CREATE TABLE IF NOT EXISTS acting_sessions (
+  session_id TEXT PRIMARY KEY, requester_aad TEXT NOT NULL, actor_aad TEXT NOT NULL, created_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS review_notices (session_id TEXT, actor_aad TEXT, requester_aad TEXT, pull TEXT, delivered INTEGER,
+    reason TEXT, at REAL);
+CREATE TABLE IF NOT EXISTS assistant_messages (
+  channel_message_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, actions TEXT NOT NULL, sent_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS teams_users (
+  teams_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, name TEXT NOT NULL DEFAULT '', updated_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS github_notices (
+  aad_id TEXT NOT NULL, kind TEXT NOT NULL, at REAL NOT NULL, PRIMARY KEY (aad_id, kind));
+CREATE TABLE IF NOT EXISTS recent_repos (
+  aad_id TEXT NOT NULL, repo_key TEXT NOT NULL, repo TEXT NOT NULL, branch TEXT NOT NULL DEFAULT '', seq INTEGER NOT NULL,
+  PRIMARY KEY (aad_id, repo_key, branch));
+CREATE TABLE IF NOT EXISTS pending_repo (
+  aad_id TEXT PRIMARY KEY, repo TEXT NOT NULL, branch TEXT NOT NULL DEFAULT '', set_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS session_history (
+  aad_id TEXT NOT NULL, session_id TEXT NOT NULL, title TEXT NOT NULL DEFAULT '', repo TEXT NOT NULL DEFAULT '',
+  branch TEXT NOT NULL DEFAULT '', last_at REAL NOT NULL, seq INTEGER NOT NULL, PRIMARY KEY (aad_id, session_id));
+CREATE TABLE IF NOT EXISTS remote_state (
+  aad_id TEXT PRIMARY KEY, session_id TEXT, connector_id TEXT NOT NULL DEFAULT '', agent_id TEXT NOT NULL DEFAULT '',
+  agent_label TEXT NOT NULL DEFAULT '', host TEXT NOT NULL DEFAULT '', cwd TEXT NOT NULL DEFAULT '',
+  cursor TEXT NOT NULL DEFAULT '', turn_open INTEGER NOT NULL DEFAULT 0, mode TEXT NOT NULL DEFAULT '',
+  modes_json TEXT NOT NULL DEFAULT '[]', listing_json TEXT NOT NULL DEFAULT '[]', updated_at REAL NOT NULL,
+  unattended INTEGER, mode_flags_json TEXT NOT NULL DEFAULT '{}');
+CREATE TABLE IF NOT EXISTS remote_session_names (
+  session_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, title TEXT NOT NULL DEFAULT '', conversation_ref TEXT NOT NULL DEFAULT '',
+  created_at REAL NOT NULL, acp_session_id TEXT NOT NULL DEFAULT '');
+CREATE TABLE IF NOT EXISTS remote_permissions (
+  session_id TEXT NOT NULL, action_id TEXT NOT NULL, aad_id TEXT NOT NULL, tool TEXT NOT NULL,
+  options_json TEXT NOT NULL, expires_at REAL NOT NULL, state TEXT NOT NULL DEFAULT 'pending', created_at REAL NOT NULL,
+  PRIMARY KEY (session_id, action_id));
+CREATE TABLE IF NOT EXISTS personal_clicks (
+  aad_id TEXT PRIMARY KEY, at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS assistant_cards (
+  card_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, item_id TEXT NOT NULL, version INTEGER NOT NULL,
+  can_accept INTEGER NOT NULL, state TEXT NOT NULL DEFAULT 'open', created_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS auto_replies (
+  aad_id TEXT NOT NULL, item_id TEXT NOT NULL, pull TEXT NOT NULL, created_at REAL NOT NULL, PRIMARY KEY (aad_id, item_id));
+CREATE TABLE IF NOT EXISTS assistant_action_cards (
+  card_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, channel_message_id TEXT NOT NULL, name TEXT NOT NULL, args TEXT NOT NULL,
+  state TEXT NOT NULL DEFAULT 'open', created_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS assistant_confirm_cards (
+  card_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, confirmation_id TEXT NOT NULL, kind TEXT NOT NULL, label TEXT NOT NULL DEFAULT '',
+  state TEXT NOT NULL DEFAULT 'open', created_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS asker_follows (
+  item_id TEXT PRIMARY KEY, batch_id TEXT NOT NULL, review_json TEXT NOT NULL, reference_json TEXT NOT NULL,
+  said TEXT NOT NULL DEFAULT '', reviewer_told INTEGER NOT NULL DEFAULT 0, deadline REAL NOT NULL, created_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS observed_groups (
+  conversation_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, scope TEXT NOT NULL, reference_json TEXT NOT NULL,
+  name TEXT NOT NULL DEFAULT '', on_since REAL, updated_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS observe_cards (
+  card_id TEXT PRIMARY KEY, aad_id TEXT NOT NULL, conversation_id TEXT NOT NULL, run_id TEXT NOT NULL, seq INTEGER NOT NULL,
+  tool TEXT NOT NULL, args TEXT NOT NULL, message TEXT NOT NULL DEFAULT '', state TEXT NOT NULL DEFAULT 'open',
+  created_at REAL NOT NULL);
+CREATE INDEX IF NOT EXISTS observe_cards_by_suggestion ON observe_cards (aad_id, run_id, seq);

package/dist/types/claw/answers.d.ts

@@ -0,0 +1,11 @@
+import { type JsonObject } from "@primusclaw/personal-agent";
+/** The answer's `data` object. */
+export declare function dataOf(answer: unknown, what: string): JsonObject;
+/** The answer's `data` list, the objects in it only. */
+export declare function rowsOf(answer: unknown, what: string): JsonObject[];
+/** The answer's `data`, whatever it is (an answer without the field is not one). */
+export declare function anyDataOf(answer: unknown, what: string): unknown;
+/** The answer itself, as an object. */
+export declare function objectOf(answer: unknown, what: string): Record<string, unknown>;
+/** `message_id` of a message Claw took, or null when it queued it behind a running turn (`{"queued": true}`). */
+export declare function messageIdOf(answer: unknown): string | null;

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

@@ -0,0 +1,27 @@
+import { type AssistantMessageOptions, type ClawAssistantPort, type ClawCredential, type JsonObject, type ReviewStart, type StartReviews } from "@primusclaw/personal-agent";
+import { type ClawHttp } from "./http.js";
+/** A message to the assistant only has to be taken: its answer comes back as an event. */
+export declare const ASSISTANT_SEND_TIMEOUT_MS = 15000;
+/** What Claw takes of the asker's own words, which it quotes to the reviewer as untrusted. */
+export declare const REQUESTER_NOTE_MAX = 2000;
+/** A review asked of someone else carries that person's exchanged token and own linked key in these. */
+export declare const ACTING_TOKEN_HEADER = "x-acting-as-token";
+export declare const ACTING_KEY_HEADER = "x-acting-as-api-key";
+/** `ClawAssistantPort` over Claw's HTTP API. */
+export declare class HttpAssistant implements ClawAssistantPort {
+    private readonly http;
+    constructor(http: ClawHttp);
+    session(key: ClawCredential): Promise<{
+        sessionId: string;
+        created: boolean;
+    }>;
+    send(key: ClawCredential, sessionId: string, text: string, options?: AssistantMessageOptions): Promise<string | null>;
+    brief(key: ClawCredential, lang: string, timezone: string): Promise<JsonObject>;
+    decideConfirmation(token: ClawCredential, confirmationId: string, decision: string): Promise<JsonObject>;
+    startReviews(token: ClawCredential, request: StartReviews): Promise<ReviewStart[]>;
+    observeScope(key: ClawCredential, scope: string): Promise<JsonObject>;
+    observe(key: ClawCredential, scope: string, content: string, messageId: string): Promise<JsonObject>;
+    observations(key: ClawCredential, scope: string, limit?: number): Promise<JsonObject[]>;
+}
+/** `data` when it is an object, else the answer itself (Python's `out["data"] if isinstance(...) else out`). */
+export declare function dataOrSelf(out: Record<string, unknown>): JsonObject;

package/dist/types/claw/client.d.ts

@@ -0,0 +1,23 @@
+import { type ClawPort, type Clock, type Logger } from "@primusclaw/personal-agent";
+import { type Fetch } from "./http.js";
+/** What Claw's audit trail calls this client by default (`X-Claw-Client`). */
+export declare const DEFAULT_CLIENT_LABEL = "clawy";
+/** How the Claw client is made (from the worker's settings). */
+export interface ClawClientOptions {
+    /** CLAW_API_URL, without a trailing slash. */
+    readonly baseUrl: string;
+    readonly clock: Clock;
+    readonly logger?: Logger;
+    /** CLAW_PLUGIN_ID (null: plain sessions). */
+    readonly pluginId?: number | null;
+    /** CLAWY_MODEL ("" sends none). */
+    readonly model?: string;
+    /** CLAW_RULE_TOOL_ID (null: no rule rides on a message). */
+    readonly ruleToolId?: number | null;
+    /** What Claw's audit trail calls this client. */
+    readonly clientLabel?: string;
+    /** The `fetch` to use (a test passes a fake). */
+    readonly fetch?: Fetch;
+}
+/** Claw's public HTTP API, always called as one person with that person's own credential. */
+export declare function createClawClient(options: ClawClientOptions): ClawPort;

package/dist/types/claw/http.d.ts

@@ -0,0 +1,64 @@
+import { ClawUnreachable, type ClawCredential } from "@primusclaw/personal-agent";
+/** What every call waits for at most, unless it says otherwise (the Python worker's client timeout). */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** The `fetch` this client uses; a test passes a fake. */
+export type Fetch = (url: string, init: RequestInit) => Promise<Response>;
+/** One request to Claw. */
+export interface ClawRequest {
+    readonly method: string;
+    /** Path and query, starting with `/`; every id in it already passed `segment` or `pyQuote`. */
+    readonly path: string;
+    readonly key: ClawCredential;
+    readonly body?: unknown;
+    /** A multipart body instead of JSON (`fetch` writes its content type). */
+    readonly form?: FormData;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly timeoutMs?: number;
+}
+/**
+ * `value` for one segment of a Claw request path. Ids reach this client from stored rows and from card actions a person
+ * can edit, so anything that could change which endpoint or host a request reaches is refused before a request is made,
+ * as ClawError(404): the answer Claw gives for an id that is not the caller's.
+ */
+export declare function segment(value: string | number): string;
+/** Python's `urllib.parse.quote(value, safe="")`: everything but letters, digits and `_.-~` percent-encoded (UTF-8). */
+export declare function pyQuote(value: string): string;
+/** The bearer header of a credential. */
+export declare function auth(key: ClawCredential): Record<string, string>;
+/** Refuses a call that must carry an exchanged identity token when `key` is an API key, before anything goes out. */
+export declare function requireToken(key: ClawCredential, what: string): void;
+/**
+ * The header that carries a person's own linked key next to an identity token, or none. It never rides next to an `ak-`
+ * credential, which would make it a second key of the same person on a request Claw refuses for a key.
+ */
+export declare function modelKeyHeader(key: ClawCredential, modelKey: string | undefined): Record<string, string>;
+/** The low-level HTTP of the Claw client: one place that sends, times out, and turns failures into core's errors. */
+export declare class ClawHttp {
+    readonly baseUrl: string;
+    private readonly fetch;
+    constructor(baseUrl: string, fetchImpl: Fetch);
+    /** Sends the request; the response whatever its status. Network failures and timeouts are ClawUnreachable. */
+    send(request: ClawRequest, extra?: RequestInit): Promise<Response>;
+    /** A call whose answer is JSON; an error status is ClawError, a body that is not JSON ClawAnswerInvalid. */
+    json(request: ClawRequest): Promise<unknown>;
+    /**
+     * A GET whose reply is refused (ReplayRefused) once it is larger than `maxBytes`, before it is decoded: it is read in
+     * pieces and never held whole beyond that. Asked for and read as it is on the wire (`Accept-Encoding: identity`); a
+     * reply that comes content-encoded all the same is refused unread. An error reply is only quoted (512 bytes).
+     */
+    boundedJson(request: ClawRequest, maxBytes: number, signal?: AbortSignal): Promise<unknown>;
+    /**
+     * A GET's status and body, the body refused (ReplayRefused) once it is larger than `maxBytes`, read in pieces and
+     * never held whole beyond that; an error body is cut at 512 bytes. Asked for and read as it is on the wire.
+     */
+    boundedBytes(request: ClawRequest, maxBytes: number, signal?: AbortSignal): Promise<{
+        status: number;
+        bytes: Uint8Array;
+    }>;
+}
+/** The first 200 characters of an error answer. */
+export declare function head(text: string): string;
+/** The body as text; a connection that breaks while it is read is ClawUnreachable. */
+export declare function readText(response: Response, what: string): Promise<string>;
+/** A failure to reach Claw, as core's error: never connected, timed out (or aborted), or broken after it was sent. */
+export declare function unreachable(err: unknown, what: string): ClawUnreachable;

package/dist/types/claw/identity-lookup.d.ts

@@ -0,0 +1,15 @@
+import { type IdentityLookup, type KeyOwner } from "@primusclaw/personal-agent";
+import { type Fetch } from "./http.js";
+/**
+ * Who a key belongs to, from the platform's `/users/self` asked with the key itself (the Python worker's `safe.whoami`,
+ * `safe.safe_user` and `safe.user_id_of`, which read the same answer). Any failure is no owner: an answer other than
+ * 200, a timeout or a broken connection, a body that is not JSON or not an object. The caller says so, or tries again
+ * later (the subscriptions' timer that fills in Claw user ids).
+ */
+export declare class HttpIdentityLookup implements IdentityLookup {
+    private readonly timeoutMs;
+    private readonly http;
+    /** `safeApiUrl` is the platform API without a trailing slash (Settings.safeApiUrl). */
+    constructor(safeApiUrl: string, fetchImpl?: Fetch, timeoutMs?: number);
+    ownerOfKey(key: string): Promise<KeyOwner | undefined>;
+}

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

@@ -0,0 +1,5 @@
+export { createClawClient, DEFAULT_CLIENT_LABEL, type ClawClientOptions } from "./client.js";
+export type { Fetch } from "./http.js";
+export { HttpIdentityLookup } from "./identity-lookup.js";
+export { HttpKeyRevoker } from "./key-revoker.js";
+export { ruleText } from "./rule.js";

package/dist/types/claw/key-revoker.d.ts

@@ -0,0 +1,22 @@
+import { type KeyRevoker } from "@primusclaw/personal-agent";
+import { type Fetch } from "./http.js";
+/**
+ * Deletes a person's own platform key with the key itself (the Python worker's `safe.revoke_own_key`): it asks
+ * `/apikeys/current` for the key's id, then deletes `/apikeys/{id}`. True only when the delete answered below 300. Any
+ * failure is false, and nothing is thrown for it: an answer other than 200 to the first call, a timeout or a broken
+ * connection, a body that is not JSON, not an object or without an id. The caller tells the person to delete the key
+ * themselves; the link goes either way.
+ *
+ * The id goes into the delete's path only as one path segment (`pathId`): a positive integer, or a string of URL
+ * unreserved characters that is not a dot segment. For any other id nothing is deleted and the answer is false: the
+ * HTTP client would resolve "../users/self" into a request for another endpoint.
+ */
+export declare class HttpKeyRevoker implements KeyRevoker {
+    private readonly timeoutMs;
+    private readonly http;
+    /** `safeApiUrl` is the platform API without a trailing slash (Settings.safeApiUrl). */
+    constructor(safeApiUrl: string, fetchImpl?: Fetch, timeoutMs?: number);
+    revoke(key: string): Promise<boolean>;
+    /** The key's id from `/apikeys/current` (Python: `body.get("id") or (body.get("data") or {}).get("id")`), or none. */
+    private currentKeyId;
+}

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

@@ -0,0 +1,23 @@
+import { type ClawCredential, type ClawRemoteAgentsPort, type JsonObject, type NewRemoteSession, type RemoteConnector, type RemoteEventRow, type RemoteHidden, type RemotePairing, type RemoteSession, type RemoteSetup, type SseEvent } from "@primusclaw/personal-agent";
+import { type ClawHttp } from "./http.js";
+/** `ClawRemoteAgentsPort` over Claw's HTTP API; every call names this client (`X-Claw-Client`) in Claw's audit trail. */
+export declare class HttpRemoteAgents implements ClawRemoteAgentsPort {
+    #private;
+    private readonly http;
+    private readonly clientLabel;
+    constructor(http: ClawHttp, clientLabel: string);
+    setup(key: ClawCredential): Promise<RemoteSetup>;
+    connectors(key: ClawCredential, options?: {
+        includeHidden?: boolean;
+    }): Promise<RemoteConnector[]>;
+    pair(key: ClawCredential): Promise<RemotePairing>;
+    hide(key: ClawCredential, connectorId: string, refs: readonly string[], hidden: boolean): Promise<RemoteHidden>;
+    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>;
+    command(key: ClawCredential, sessionId: string, body: Readonly<JsonObject>, idempotencyKey?: string): Promise<JsonObject>;
+    decide(key: ClawCredential, sessionId: string, actionId: string, optionId: string): Promise<JsonObject>;
+    events(key: ClawCredential, sessionId: string, after?: string, limit?: number): Promise<RemoteEventRow[]>;
+    stream(key: ClawCredential, sessionId: string, after?: string, signal?: AbortSignal): AsyncIterable<SseEvent>;
+}

package/dist/types/claw/rule.d.ts

@@ -0,0 +1,20 @@
+import { type ClawCredential, type Clock, type Logger } from "@primusclaw/personal-agent";
+import { type ClawHttp } from "./http.js";
+/** A rule download is a zip of one file of at most RULE_MAX_BYTES; a larger answer is refused before it is held. */
+export declare const RULE_DOWNLOAD_MAX_BYTES: number;
+/** The text of a rule tool as `GET /v1/tools/<id>/download` returns it: a zip holding one small markdown file. */
+export declare function ruleText(download: Uint8Array): string;
+/**
+ * The reply-style rule: a public rule tool of Claw (CLAW_RULE_TOOL_ID), read with the caller's key and kept for
+ * RULE_TTL_MS. When it cannot be read the last copy is used, else none: the person's message still goes.
+ */
+export declare class StyleRule {
+    private readonly http;
+    private readonly toolId;
+    private readonly clock;
+    private readonly logger;
+    private copy;
+    constructor(http: ClawHttp, toolId: number, clock: Clock, logger: Logger);
+    text(key: ClawCredential): Promise<string>;
+    private download;
+}

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

@@ -0,0 +1,56 @@
+import { type ClawCredential, type ClawSessionsPort, type JsonObject, type NewSession, type SendOptions, type SseEvent, type UploadFile } from "@primusclaw/personal-agent";
+import { type ClawHttp } from "./http.js";
+import type { StyleRule } from "./rule.js";
+/** Claw takes a file for this many days (one of its tiers: 1, 2, 7, 15, 30). */
+export declare const UPLOAD_TTL_DAYS = 7;
+/** The newest event alone is a few KB; more is a Claw that ignored `tail=1` and sent everything. */
+export declare const LAST_EVENT_MAX_BYTES = 262144;
+/** A changes reply lists at most 200 files per repository: a few hundred KB at the very most. */
+export declare const CHANGES_MAX_BYTES = 1048576;
+/** What a session's messages carry besides the text. */
+export interface MessageDefaults {
+    /** CLAW_PLUGIN_ID, named as the web client names it (`pluginId`); null none. */
+    readonly pluginId: number | null;
+    /** CLAWY_MODEL: what a new session asks for when its caller names none ("" none). */
+    readonly model: string;
+    /** The reply-style rule, when a rule tool is configured. */
+    readonly rule: StyleRule | null;
+}
+/** `ClawSessionsPort` over Claw's HTTP API. */
+export declare class HttpSessions implements ClawSessionsPort {
+    #private;
+    private readonly http;
+    private readonly defaults;
+    constructor(http: ClawHttp, defaults: MessageDefaults);
+    checkKey(key: ClawCredential): Promise<void>;
+    create(key: ClawCredential, session: NewSession): Promise<{
+        sessionId: string;
+        messageId: string;
+    }>;
+    uploadFiles(key: ClawCredential, sessionId: string, folder: string, files: readonly UploadFile[]): Promise<{
+        paths: string[];
+        refused: string[];
+    }>;
+    setModel(key: ClawCredential, sessionId: string, model: string): Promise<void>;
+    sendMessage(key: ClawCredential, sessionId: string, text: string, options?: SendOptions): Promise<string | null>;
+    turn(key: ClawCredential, sessionId: string): Promise<{
+        running: boolean;
+        messageId: string | null;
+    }>;
+    events(key: ClawCredential, sessionId: string, options?: {
+        tail?: number;
+        maxBytes?: number;
+    }): Promise<JsonObject[]>;
+    lastEventId(key: ClawCredential, sessionId: string): Promise<string | null>;
+    changes(key: ClawCredential, sessionId: string, timeoutMs: number): Promise<unknown>;
+    deliveryLink(sessionId: string, deliveryId: string): string | null;
+    interrupt(key: ClawCredential, sessionId: string): Promise<void>;
+    decide(key: ClawCredential, sessionId: string, toolUseId: string, action: string, options?: {
+        acting?: boolean;
+    }): Promise<void>;
+    answer(key: ClawCredential, sessionId: string, toolUseId: string, answers: Readonly<Record<string, string>>, skipped: readonly string[], options?: {
+        acting?: boolean;
+    }): Promise<void>;
+    vote(key: ClawCredential, sessionId: string, messageId: string, vote: "up" | "down", reason?: string): Promise<void>;
+    stream(key: ClawCredential, sessionId: string, after?: string, signal?: AbortSignal, onOpen?: () => void): AsyncIterable<SseEvent>;
+}

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

@@ -0,0 +1,46 @@
+import { type ClawCredential, type ClawMergeConfirmationsPort, type ClawNotificationsPort, type ClawSettingsPort, type ClawSubscription, type ClawTriggersPort, type GithubConnection, type JsonObject, type MemoryState, type TriggerInput } from "@primusclaw/personal-agent";
+import { type ClawHttp } from "./http.js";
+/** `ClawSettingsPort` over Claw's HTTP API. */
+export declare class HttpSettings implements ClawSettingsPort {
+    #private;
+    private readonly http;
+    constructor(http: ClawHttp);
+    memory(key: ClawCredential, limit?: number): Promise<MemoryState>;
+    setMemory(key: ClawCredential, enabled: boolean): Promise<{
+        enabled: boolean;
+        available: boolean;
+    }>;
+    models(key: ClawCredential): Promise<string[]>;
+    assistantSettings(token: ClawCredential): Promise<JsonObject | null>;
+    reviewMode(token: ClawCredential): Promise<string>;
+    setReviewMode(token: ClawCredential, mode: string): Promise<void>;
+    githubConnection(token: ClawCredential): Promise<GithubConnection | null>;
+}
+/** `ClawNotificationsPort` over Claw's HTTP API. */
+export declare class HttpNotifications implements ClawNotificationsPort {
+    private readonly http;
+    constructor(http: ClawHttp);
+    list(key: ClawCredential): Promise<ClawSubscription[]>;
+    create(key: ClawCredential, url: string, eventTypes?: readonly string[], sources?: readonly string[]): Promise<ClawSubscription>;
+    updateTypes(key: ClawCredential, subscriptionId: string, eventTypes: readonly string[], options?: {
+        enable?: boolean;
+        sources?: readonly string[];
+    }): Promise<ClawSubscription>;
+    delete(key: ClawCredential, subscriptionId: string): Promise<void>;
+}
+/** `ClawTriggersPort` over Claw's HTTP API. */
+export declare class HttpTriggers implements ClawTriggersPort {
+    private readonly http;
+    constructor(http: ClawHttp);
+    list(key: ClawCredential): Promise<JsonObject[]>;
+    create(key: ClawCredential, trigger: TriggerInput): Promise<JsonObject>;
+    update(key: ClawCredential, triggerId: string, trigger: TriggerInput): Promise<JsonObject>;
+    delete(key: ClawCredential, triggerId: string): Promise<void>;
+}
+/** `ClawMergeConfirmationsPort` over Claw's HTTP API. */
+export declare class HttpMergeConfirmations implements ClawMergeConfirmationsPort {
+    private readonly http;
+    constructor(http: ClawHttp);
+    pending(key: ClawCredential, sessionId: string): Promise<JsonObject[]>;
+    decide(token: ClawCredential, confirmationId: string, decision: string): Promise<JsonObject>;
+}

package/dist/types/claw/sse-stream.d.ts

@@ -0,0 +1,14 @@
+import { type ClawCredential, type SseEvent } from "@primusclaw/personal-agent";
+import { type ClawHttp } from "./http.js";
+/** Claw sends a keepalive every 15 s; silence this long means a dead stream. */
+export declare const STREAM_IDLE_MS = 90000;
+/** Options of an SSE read (tests shorten the waits). */
+export interface StreamTiming {
+    readonly connectMs?: number;
+    readonly idleMs?: number;
+}
+/**
+ * The events of a Claw SSE stream at `path` (history after `after`, then live). The connection is given `connectMs` to
+ * answer and is dropped (ClawUnreachable "timeout") after `idleMs` with nothing read; `signal` ends it early.
+ */
+export declare function sseEvents(http: ClawHttp, path: string, key: ClawCredential, after: string | undefined, signal?: AbortSignal, timing?: StreamTiming, onOpen?: () => void): AsyncGenerator<SseEvent>;

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

@@ -0,0 +1,22 @@
+import { type AskerView, type BoardState, type ClawCredential, type ClawWorkItemsPort, type Decision, type JsonObject, type ReviewAskedOfOther, type WorkItem } from "@primusclaw/personal-agent";
+import { type ClawHttp } from "./http.js";
+/** `ClawWorkItemsPort` over Claw's HTTP API. */
+export declare class HttpWorkItems implements ClawWorkItemsPort {
+    #private;
+    private readonly http;
+    constructor(http: ClawHttp);
+    list(key: ClawCredential, state?: BoardState): Promise<WorkItem[]>;
+    askedOfOthers(key: ClawCredential): Promise<ReviewAskedOfOther[]>;
+    get(key: ClawCredential, itemId: string): Promise<WorkItem>;
+    requesterView(key: ClawCredential, itemId: string): Promise<AskerView>;
+    accept(key: ClawCredential, itemId: string, version: number): Promise<Decision>;
+    retry(key: ClawCredential, itemId: string): Promise<Decision>;
+    stop(key: ClawCredential, itemId: string): Promise<Decision>;
+    pulls(key: ClawCredential, itemId: string): Promise<{
+        item: WorkItem;
+        pulls: string[];
+    }>;
+    watchPull(token: ClawCredential, itemId: string, pull: string, reply?: boolean): Promise<JsonObject>;
+    watches(key: ClawCredential, itemId: string): Promise<JsonObject[]>;
+    unwatchPull(key: ClawCredential, itemId: string, subId: string): Promise<JsonObject>;
+}

package/dist/types/claw/zip.d.ts

@@ -0,0 +1,15 @@
+/** One file of a zip archive, as its central directory lists it. */
+export interface ZipEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    /** The uncompressed size the archive declares. */
+    readonly size: number;
+    /** The file's bytes (read on demand: a file is only inflated when it is wanted). */
+    read(): Uint8Array;
+}
+/** Not a zip archive this reader understands (Python's `zipfile.is_zipfile` false, or a damaged archive). */
+export declare class NotAZip extends Error {
+    readonly name = "NotAZip";
+}
+/** The files a zip archive lists, stored or deflated (the two methods a rule download uses). */
+export declare function readZip(bytes: Uint8Array): ZipEntry[];

package/dist/types/config/env.d.ts

@@ -0,0 +1,29 @@
+/** The process environment, or a test's. */
+export type Env = Readonly<Record<string, string | undefined>>;
+/** Reads settings out of an environment, with the worker's rules: a typo stops the worker, it never picks a value. */
+export declare class EnvReader {
+    readonly env: Env;
+    constructor(env: Env);
+    /** The raw value ("" unset). */
+    raw(name: string, fallback?: string): string;
+    /** The value without surrounding white space ("" unset). */
+    text(name: string, fallback?: string): string;
+    /** A value that must be set and not blank. */
+    required(name: string): string;
+    /** On or off; `fallback` when unset or empty; anything else stops the worker. */
+    switch(name: string, fallback: boolean): boolean;
+    /** On only for the words that mean on (the older switches, which read anything else as off). */
+    isOn(name: string): boolean;
+    /** A positive whole number; `fallback` when unset or empty; anything else stops the worker. */
+    positiveInt(name: string, fallback: number): number;
+    /** A whole number (Python's `int()` of the value: a sign, surrounding space and `_` between digits allowed). */
+    int(name: string, fallback: string): number;
+    /** A whole number, or null when unset or blank. */
+    optionalInt(name: string): number | null;
+    /** A comma separated list, blank entries dropped; `lower` lower-cases each entry. */
+    list(name: string, lower?: boolean): string[];
+}
+/** Python's `repr()` of a string, for an error message that quotes a value the way the Python worker did. */
+export declare function pyRepr(value: string): string;
+/** `value` without a trailing slash (Python's `rstrip("/")`). */
+export declare function withoutTrailingSlash(value: string): string;

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

@@ -0,0 +1,3 @@
+export { EnvReader, pyRepr, withoutTrailingSlash, type Env } from "./env.js";
+export { ENV_NAMES, EnvSecretSource, secretsSourceOf, wantedSecrets } from "./secrets.js";
+export { ASSISTANT_REPLY_WINDOW_SECONDS, GITHUB_CLI_CLIENT_ID, readSettings } from "./settings.js";

package/dist/types/config/secrets.d.ts

@@ -0,0 +1,21 @@
+import { type SecretName, type SecretSource, type SecretsSourceName } from "@primusclaw/personal-agent";
+import { type Env } from "./env.js";
+/** Where SECRETS_SOURCE=env finds each secret: an environment variable, or (the GitHub App's key) the file it names. */
+export declare const ENV_NAMES: Readonly<Record<SecretName, string>>;
+/** SECRETS_SOURCE: env (the default) or keyvault; a typo stops the worker. */
+export declare function secretsSourceOf(env: Env): SecretsSourceName;
+/**
+ * The secrets this configuration needs: the encryption keys always, the exchange's client secret when the exchange is
+ * on, the GitHub App's key when the feedback App is configured.
+ */
+export declare function wantedSecrets(env: Env): SecretName[];
+/** SECRETS_SOURCE=env: the secrets from the environment (a Kubernetes Secret) and the mounted key file. */
+export declare class EnvSecretSource implements SecretSource {
+    private readonly env;
+    private readonly readFile;
+    readonly name = "env";
+    constructor(env: Env, readFile?: (path: string) => string);
+    load(names: readonly SecretName[]): Promise<ReadonlyMap<SecretName, string>>;
+    private read;
+    private keyFile;
+}

package/dist/types/config/settings.d.ts

@@ -0,0 +1,13 @@
+import { type SecretName, type Settings } from "@primusclaw/personal-agent";
+import { type Env } from "./env.js";
+/** The public client id of the GitHub CLI: an OAuth app most organizations already allow; its device flow needs no secret. */
+export declare const GITHUB_CLI_CLIENT_ID = "178c6fc778ccc68e1d6a";
+/** The default of ASSISTANT_REPLY_WINDOW_SECONDS. */
+export declare const ASSISTANT_REPLY_WINDOW_SECONDS: number;
+/**
+ * The worker's channel-neutral settings from the environment (the Python worker's `Settings.from_env`, without the
+ * Teams fields). `secrets` are what the deployment's SecretSource loaded; a name it holds is taken from there and never
+ * from the environment, and with SECRETS_SOURCE=keyvault a secret it does not hold stops the worker. Every malformed
+ * value stops it too (ConfigError), with the message the Python worker gave.
+ */
+export declare function readSettings(env: Env, secrets?: ReadonlyMap<SecretName, string>): Settings;

package/dist/types/context/als-request-scope.d.ts

@@ -0,0 +1,3 @@
+import type { RequestScope } from "@primusclaw/personal-agent";
+/** A scope of its own: contexts entered in one are not seen through another. */
+export declare function alsRequestScope(): RequestScope;

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

@@ -0,0 +1,37 @@
+/** The token is not one of these keys' (or is malformed, tampered with, or out of its ttl). */
+export declare class InvalidToken extends Error {
+    readonly name = "InvalidToken";
+}
+export interface FernetOptions {
+    /** Wall-clock seconds, for the token's timestamp and a ttl check (default: the system clock). */
+    readonly nowSeconds?: () => number;
+    /** IV bytes (default: `node:crypto` randomBytes). */
+    readonly randomBytes?: (n: number) => Uint8Array;
+}
+export declare class Fernet {
+    #private;
+    constructor(key: string | Uint8Array, options?: FernetOptions);
+    /** A new key, as Python's `Fernet.generate_key()` gives it. */
+    static generateKey(): string;
+    /** The signing half of the key (for tests that check a derived key is not it). */
+    get signingKey(): Uint8Array;
+    encrypt(data: string | Uint8Array): string;
+    encryptAtTime(data: string | Uint8Array, currentTime: number): string;
+    /** The token for exactly these parts (the spec's generate vectors fix the IV). */
+    encryptFromParts(data: Uint8Array, currentTime: number, iv: Uint8Array): string;
+    /** The plaintext. Without `ttl` (how the store decrypts) the token's age is not checked. */
+    decrypt(token: string | Uint8Array, ttl?: number): Uint8Array;
+    decryptAtTime(token: string | Uint8Array, ttl: number, currentTime: number): Uint8Array;
+    /** @internal Shared with MultiFernet.rotate, which must not re-parse the token per key. */
+    decryptData(data: Uint8Array, timestamp: number, timeInfo?: readonly [number, number]): Uint8Array;
+    private verifySignature;
+}
+/** Encrypts with the first key, decrypts with any, and rotates a token to the first key keeping its timestamp. */
+export declare class MultiFernet {
+    #private;
+    constructor(fernets: readonly Fernet[]);
+    get primary(): Fernet;
+    encrypt(data: string | Uint8Array): string;
+    decrypt(token: string | Uint8Array, ttl?: number): Uint8Array;
+    rotate(token: string | Uint8Array, randomIv?: (n: number) => Uint8Array): string;
+}

package/dist/types/crypto/link-code.d.ts

@@ -0,0 +1,6 @@
+/** The label the key is derived under. A new label is a new key: every pending code is void. */
+export declare const LINK_HASH_LABEL = "primusclaw-teams/link-code-hmac/v1";
+/** The HMAC key link codes are hashed under, derived from one Fernet key of TEAMS_ENCRYPTION_KEYS. */
+export declare function linkHashKey(fernetKey: string): Uint8Array;
+/** A link code as it is stored (hex). */
+export declare function hashLinkCode(code: string, key: Uint8Array): string;