@primusclaw/personal-agent 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,107 @@
+import type { Lang } from "../locales/lang.js";
+import type { Conversation, InboundAction, InboundMessage, InboundVote, OutMessage, UserRef } from "./surface.js";
+/**
+ * How features plug into the router (the Python worker's `Agent._dispatch` and `Agent._route_group`). The router only
+ * dispatches: it reads who sent what and where, applies the chat's own rules (rate, account, language, the chat's
+ * commands), and hands the event to the first feature that takes it. A feature registers
+ *
+ *  - `MessageInterceptor`s: read a message before the router's own reading of it (a review request, a feedback
+ *    answer, an observed group's message). Run in the order the assembly lists them; the first that takes it ends it.
+ *  - `CommandHandler`s: carry out a command word the router does not own (`/brief`, `/github`, `/board`).
+ *  - `ClickHandler`s: answer the buttons of the cards the feature posts, by the card's verb.
+ *
+ * Every handler is given the conversation to answer in and the person's language at that moment; a click handler
+ * settles the click it was given (`ClickRoute.settle`), and the router settles whatever a handler left open.
+ */
+/** What every routed event carries. */
+export interface RouteBase {
+    readonly sender: UserRef;
+    /** Where to answer. In a group chat the conversation masks credential shapes in everything it posts. */
+    readonly conversation: Conversation;
+    /** The chat a person's state is kept under: "" for their 1:1 chat, the conversation id of a group chat. */
+    readonly scope: string;
+    /** The language the person is answered in now (it can change while the event is handled: read it when saying). */
+    lang(): Lang;
+}
+export interface MessageRoute extends RouteBase {
+    readonly message: InboundMessage;
+    /**
+     * The message as commands read it: a word of the commands menu as its command (`help` is `/help`) and a sentence help
+     * teaches as the command it means (`停一下` is `/stop`). `message.text` is what the person wrote.
+     */
+    readonly text: string;
+}
+/** How a click handler replaces the clicked card. */
+export interface SettleOptions {
+    /** The outcome's one line, said as a new message when `card` is more than a note (a phone does not redraw an edit). */
+    readonly fallback?: string;
+    /** False for a handler that has already posted its outcome as a message of its own. */
+    readonly announce?: boolean;
+}
+export interface ClickRoute extends RouteBase {
+    readonly action: InboundAction;
+    /**
+     * THE way a handler ends a click: the clicked card is replaced (by `card`, or by a note card saying `card` when it is
+     * text), and the outcome is also said as a new message. True when the card was replaced. Never throws for a failed
+     * edit once the outcome was said.
+     */
+    settle(card: OutMessage | string, options?: SettleOptions): Promise<boolean>;
+}
+/** A message read before the router's own reading of it. */
+export interface MessageInterceptor {
+    /** For logs and tests. */
+    readonly name: string;
+    /** True when it took the message: nothing after it reads the message. */
+    intercept(route: MessageRoute): Promise<boolean>;
+}
+export interface CommandRoute extends RouteBase {
+    /** What Claw is called with for this person (their linked key, or an exchanged token). */
+    readonly credential: string;
+    /** The message the command came in; undefined for a command the assistant asked the chat to carry out. */
+    readonly message: InboundMessage | undefined;
+}
+/** A command word the router does not carry out itself (`/brief`, `/board`, `/github`, `/agent`). */
+export interface CommandHandler {
+    /** The command word, lower case, without the slash. */
+    readonly name: string;
+    /**
+     * Read before the account check (it needs no Claw credential: `/github`, `/lang`). Such a handler is given an empty
+     * credential.
+     */
+    readonly beforeCredential?: boolean;
+    /** Carry out `/name args`; false when it did not take it (the message then goes on as the person's words). */
+    run(route: CommandRoute, args: string): Promise<boolean>;
+}
+/** The buttons of a feature's cards, by verb (the card data's `primusclaw` field). */
+export interface ClickHandler {
+    readonly verbs: readonly string[];
+    /**
+     * A click in a 1:1 chat, before the person's credential is read: true when it was answered with no Claw key (a
+     * person with no linked key, an answer given with an exchanged identity token only).
+     */
+    beforeCredential?(click: ClickRoute): Promise<boolean>;
+    /** A click in a 1:1 chat, with the person's credential. */
+    withCredential?(click: ClickRoute, credential: string): Promise<void>;
+    /** A click in a group chat: true when answered (a group answers only the buttons that may be pressed there). */
+    inGroup?(click: ClickRoute): Promise<boolean>;
+}
+export interface VoteRoute extends RouteBase {
+    readonly vote: InboundVote;
+}
+/** The channel's own thumbs under an answer (feedback's). */
+export interface VoteHandler {
+    vote(route: VoteRoute): Promise<void>;
+}
+/** The handlers a feature brings, in the order they are tried. */
+export interface RouteHandlers {
+    /** Read in a 1:1 chat before the account check. */
+    readonly personalInterceptors: readonly MessageInterceptor[];
+    /** Read in a group chat after the group's own commands, before the account check. */
+    readonly groupInterceptors: readonly MessageInterceptor[];
+    readonly commands: readonly CommandHandler[];
+    readonly clicks: readonly ClickHandler[];
+    /** The channel's thumbs (undefined: they are dropped). */
+    readonly votes?: VoteHandler;
+}
+/** No handlers. */
+export declare const noRouteHandlers: RouteHandlers;

package/dist/types/ports/secret-source.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Where the worker's secrets come from. The names are the settings they replace; how a source finds each one (an
+ * environment variable, a mounted file, a vault entry) is that source's business.
+ */
+export declare const SECRET_NAMES: readonly ["TEAMS_ENCRYPTION_KEYS", "TEAMS_EXCHANGE_CLIENT_SECRET", "FEEDBACK_GITHUB_APP_KEY"];
+export type SecretName = (typeof SECRET_NAMES)[number];
+/** The sources a deployment may name in SECRETS_SOURCE. */
+export declare const SECRETS_SOURCES: readonly ["env", "keyvault"];
+export type SecretsSourceName = (typeof SECRETS_SOURCES)[number];
+/** A secret could not be read. The message names the secret and the reason, never a value. */
+export declare class SecretsUnavailable extends Error {
+    readonly name = "SecretsUnavailable";
+}
+export interface SecretSource {
+    readonly name: SecretsSourceName;
+    /**
+     * Every one of `names`, read once at start and kept in memory only; throws SecretsUnavailable when one cannot be read
+     * (the worker stops before it takes a message: it never runs with a missing or stale secret).
+     */
+    load(names: readonly SecretName[]): Promise<ReadonlyMap<SecretName, string>>;
+}

package/dist/types/ports/store/approvals.d.ts

@@ -0,0 +1,47 @@
+/** Tool approvals pushed to a chat (table `approvals`): one approval is one card, whichever way it arrives. */
+import type { JsonObject } from "./json.js";
+export type ApprovalState = "pending" | "approved" | "denied" | "expired" | (string & {});
+export interface Approval {
+    readonly sessionId: string;
+    readonly toolUseId: string;
+    readonly userId: string;
+    readonly tool: string;
+    readonly expiresAt: number;
+    readonly state: ApprovalState;
+}
+/** An approval card that was recorded and never reached the chat: what it takes to send it again. */
+export interface UnsentCard {
+    readonly sessionId: string;
+    readonly toolUseId: string;
+    readonly userId: string;
+    readonly expiresAt: number;
+    readonly envelope: JsonObject;
+}
+export interface NewApproval {
+    readonly userId: string;
+    readonly sessionId: string;
+    readonly toolUseId: string;
+    readonly tool: string;
+    readonly expiresAt: number;
+    /** The card as it will be published, kept until `approvalSent` so a worker that dies before the send leaves it to the next. */
+    readonly envelope?: JsonObject | null;
+}
+export interface ApprovalRepository {
+    /** True when this call recorded it; false when a card for the same approval was recorded before. */
+    saveApproval(approval: NewApproval): boolean;
+    /** The card reached the chat: nothing is left to send. */
+    approvalSent(sessionId: string, toolUseId: string): void;
+    /** Its card is being sent right now by this process and may still fail. */
+    approvalInFlight(sessionId: string, toolUseId: string): boolean;
+    /** The card never reached the chat: take the record back (a row answered meanwhile stays). */
+    forgetApproval(sessionId: string, toolUseId: string): void;
+    /** Cards recorded and never sent, each marked in flight; ones out of time are closed as expired instead. */
+    claimUnsentApprovals(): UnsentCard[];
+    /** A claimed card could not be sent: the next sweep tries again. */
+    approvalSendFailed(sessionId: string, toolUseId: string): void;
+    getApproval(sessionId: string, toolUseId: string): Approval | null;
+    /** Move an approval to `state`; true if this call did it (only from 'pending' unless `onlyIfPending` is false). */
+    closeApproval(sessionId: string, toolUseId: string, state: ApprovalState, options?: {
+        readonly onlyIfPending?: boolean;
+    }): boolean;
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Cards and messages of the assistant (tables `assistant_cards`, `auto_replies`, `assistant_action_cards`,
+ * `assistant_confirm_cards`, `assistant_messages`). A card's buttons carry only its id; what a press means is read
+ * from here, so a forged, old or someone else's card changes nothing.
+ */
+import type { JsonObject } from "./json.js";
+/** 'open', 'busy' (a press is being carried out), 'done', or (work-item cards) 'ended'. */
+export type CardState = "open" | "busy" | "done" | "ended" | (string & {});
+export interface MoveOptions {
+    /** Only a card in this state moves, so of two presses exactly one is carried out. */
+    readonly onlyFrom?: CardState | null;
+}
+/** A card for result `version` of a work item. */
+export interface AssistantCard {
+    readonly cardId: string;
+    readonly userId: string;
+    readonly itemId: string;
+    readonly version: number;
+    /** It has an Accept button (a result waits); else only Stop. */
+    readonly canAccept: boolean;
+    readonly state: CardState;
+    readonly createdAt: number;
+    /** How the item ended, as the card shows it (state 'ended'). */
+    readonly ended: string;
+}
+/** An open work-item card that went out and can be edited. */
+export interface PlacedCard {
+    readonly cardId: string;
+    readonly userId: string;
+    readonly itemId: string;
+    readonly activityId: string;
+    readonly reference: JsonObject;
+    readonly render: JsonObject;
+    readonly createdAt: number;
+}
+/** A button for one of the assistant's own commands (`/{name} {args}`). */
+export interface ActionCard {
+    readonly cardId: string;
+    readonly userId: string;
+    /** The message the assistant answered: the action must be one that message declared. */
+    readonly channelMessageId: string;
+    readonly name: string;
+    readonly args: string;
+    readonly state: CardState;
+    readonly createdAt: number;
+}
+/** A card for a write Claw holds until the person answers. */
+export interface ConfirmCard {
+    readonly cardId: string;
+    readonly userId: string;
+    readonly confirmationId: string;
+    /** trigger_create | trigger_cancel | devenv_send | github_comment */
+    readonly kind: string;
+    /** What the button that lets it through says. */
+    readonly label: string;
+    readonly state: CardState;
+    readonly createdAt: number;
+}
+export interface AssistantMessage {
+    readonly userId: string;
+    /** The actions (and handoffs) the message declared. */
+    readonly actions: ReadonlySet<string>;
+}
+export interface AssistantCardRepository {
+    /** Record a card before it is sent; the id is all its buttons carry. */
+    addAssistantCard(userId: string, itemId: string, version: number, canAccept: boolean): string;
+    getAssistantCard(cardId: string): AssistantCard | null;
+    /** An open card moves to 'ended'; true if this call moved it. */
+    endAssistantCard(cardId: string, ended: string): boolean;
+    /** The card went out as the channel message `activityId` in `reference`, showing `render`. */
+    placeAssistantCard(cardId: string, placement: {
+        readonly activityId: string;
+        readonly reference: JsonObject;
+        readonly render: JsonObject;
+    }): void;
+    /** Open, posted cards: of `itemId`, or (none given) all posted since `since`, oldest first. */
+    placedAssistantCards(filter: {
+        readonly itemId: string;
+    } | {
+        readonly since?: number;
+    }): PlacedCard[];
+    moveAssistantCard(cardId: string, state: CardState, options?: MoveOptions): boolean;
+    /** Automatic replies were turned on for `itemId` on `pull`. */
+    setAutoReply(userId: string, itemId: string, pull: string): void;
+    autoReply(userId: string, itemId: string): string | null;
+    clearAutoReply(userId: string, itemId: string): void;
+}
+export interface AssistantButtonRepository {
+    addActionCard(userId: string, channelMessageId: string, name: string, args: string): string;
+    /** Null once it is older than ASSISTANT_MESSAGE_KEEP_SECONDS. */
+    getActionCard(cardId: string): ActionCard | null;
+    moveActionCard(cardId: string, state: CardState, options?: MoveOptions): boolean;
+    addConfirmCard(userId: string, confirmationId: string, kind: string, label?: string): string;
+    /** Null once it is older than CONFIRM_CARD_KEEP_SECONDS. */
+    getConfirmCard(cardId: string): ConfirmCard | null;
+    moveConfirmCard(cardId: string, state: CardState, options?: MoveOptions): boolean;
+}
+export interface AssistantMessageRepository {
+    /** A message this worker sent to the person's assistant, with the actions it declared and the Claw users it named. */
+    noteAssistantMessage(channelMessageId: string, userId: string, actions: readonly string[], people?: readonly string[]): void;
+    /** The Claw user ids the message named, while it is kept (empty otherwise). */
+    assistantMessagePeople(channelMessageId: string): ReadonlySet<string>;
+    assistantMessage(channelMessageId: string): AssistantMessage | null;
+}

package/dist/types/ports/store/feedback.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Feedback (tables `feedback_reports`, `feedback_asks`, `feedback_offers`, `feedback_prompts`). A report is written
+ * before anything is sent to GitHub, so one that cannot be delivered yet is never lost.
+ */
+import type { IssueRef } from "../../plugins/feedback-sink.js";
+export interface FeedbackReport {
+    readonly id: number;
+    readonly userId: string;
+    readonly scope: string;
+    readonly sessionId: string;
+    readonly text: string;
+    readonly scene: string;
+    readonly createdAt: number;
+    /** 'pending' (not yet in GitHub) or 'filed'. */
+    readonly state: "pending" | "filed" | (string & {});
+    readonly issueNumber: number | null;
+    readonly issueUrl: string;
+    /** Filed as a comment on an earlier report's issue. */
+    readonly asComment: boolean;
+    readonly attempts: number;
+    readonly nextAttemptAt: number;
+    readonly lastError: string;
+    readonly reporterName: string;
+    readonly reporterEmail: string;
+}
+export interface NewFeedbackReport {
+    readonly userId: string;
+    readonly scope: string;
+    readonly sessionId: string;
+    readonly text: string;
+    readonly scene: string;
+    readonly reporterName?: string;
+    readonly reporterEmail?: string;
+}
+export type FeedbackOfferState = "open" | "sending" | "done" | "declined" | (string & {});
+export interface FeedbackOffer {
+    readonly offerId: string;
+    readonly userId: string;
+    readonly issueNumber: number;
+    readonly sessionId: string;
+    readonly turnId: string;
+    readonly createdAt: number;
+    readonly state: FeedbackOfferState;
+}
+export interface FeedbackPrompt {
+    readonly promptId: string;
+    /** The person whose message went wrong: in a group, the only one who may press the button. */
+    readonly userId: string;
+    /** '' for the 1:1 chat, the conversation id for a group. */
+    readonly scope: string;
+    readonly createdAt: number;
+}
+export interface FeedbackRepository {
+    /** Returns the new report's id. */
+    addFeedbackReport(report: NewFeedbackReport): number;
+    getFeedbackReport(reportId: number): FeedbackReport | null;
+    /** The issue of the newest filed report of the same person, chat and session within FEEDBACK_DEDUPE_SECONDS. */
+    feedbackTarget(report: FeedbackReport): IssueRef | null;
+    markFeedbackFiled(reportId: number, issue: IssueRef, asComment: boolean): void;
+    /** `error` is kept to 80 characters. */
+    markFeedbackFailed(reportId: number, error: string, retryAt: number): void;
+    /** Undelivered reports whose retry time has come, oldest first. */
+    dueFeedback(limit: number): FeedbackReport[];
+    pendingFeedbackCount(): number;
+    /** A bare /feedback: the person's next message in this chat is the report. */
+    openFeedbackAsk(userId: string, scope: string): void;
+    /** True (and closed) when an unexpired ask is open. */
+    takeFeedbackAsk(userId: string, scope: string): boolean;
+    hasFeedbackAsk(userId: string, scope: string): boolean;
+    addFeedbackOffer(userId: string, issueNumber: number, sessionId: string, turnId: string): string;
+    getFeedbackOffer(offerId: string): FeedbackOffer | null;
+    /** `onlyFrom` defaults to 'open'; null moves from any state. */
+    moveFeedbackOffer(offerId: string, state: FeedbackOfferState, options?: {
+        readonly onlyFrom?: FeedbackOfferState | null;
+    }): boolean;
+    /** A "Report a problem" button; its owner is kept here, not on the card. */
+    addFeedbackPrompt(userId: string, scope: string): string;
+    /** Null once older than FEEDBACK_PROMPT_TTL_SECONDS. */
+    getFeedbackPrompt(promptId: string): FeedbackPrompt | null;
+}

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

@@ -0,0 +1,81 @@
+/** GitHub review delegation: held writes, sessions that act as someone, followed reviews and rationed notices
+ * (tables `github_confirmations`, `acting_sessions`, `review_notices`, `asker_follows`, `github_notices`). */
+import type { JsonObject } from "./json.js";
+export type ConfirmationState = "pending" | "sending" | "done" | (string & {});
+/** A write that waits for the person the review acts for. A click is checked against this row, never the card. */
+export interface GithubConfirmation {
+    /** Claw's id. */
+    readonly confirmationId: string;
+    readonly sessionId: string;
+    /** The only person who may answer. */
+    readonly actorId: string;
+    readonly requesterId: string;
+    readonly repo: string;
+    readonly pr: number;
+    readonly reference: JsonObject;
+    readonly expiresAt: number;
+    readonly state: ConfirmationState;
+    readonly createdAt: number;
+    /** 'merge', or 'review'. */
+    readonly kind: string;
+    /** Of a review: APPROVE, REQUEST_CHANGES or COMMENT; '' for a merge. */
+    readonly event: string;
+}
+export type NewGithubConfirmation = Omit<GithubConfirmation, "state" | "createdAt" | "kind" | "event"> & {
+    readonly kind?: string;
+    readonly event?: string;
+};
+export interface GithubConfirmationRepository {
+    /** False when it is already recorded (the same one is never sent twice). */
+    addGithubConfirmation(confirmation: NewGithubConfirmation): boolean;
+    getGithubConfirmation(confirmationId: string): GithubConfirmation | null;
+    /** Still waiting for this person's answer, oldest first. */
+    pendingGithubConfirmations(actorId: string): GithubConfirmation[];
+    /** False when it was not in `onlyFrom` (default 'pending'). */
+    moveGithubConfirmation(confirmationId: string, state: ConfirmationState, options?: {
+        readonly onlyFrom?: ConfirmationState;
+    }): boolean;
+    /** The card could not be sent: a pending row goes. */
+    forgetGithubConfirmation(confirmationId: string): void;
+}
+export interface ReviewNotice {
+    readonly sessionId: string;
+    readonly actorId: string;
+    readonly requesterId: string;
+    readonly pull: string;
+    readonly delivered: boolean;
+    readonly reason: string;
+}
+export interface AskerFollow {
+    readonly itemId: string;
+    readonly batchId: string;
+    readonly review: unknown;
+    readonly reference: unknown;
+    readonly said: string;
+    readonly reviewerTold: boolean;
+    readonly deadline: number;
+}
+export interface ReviewDelegationRepository {
+    /** A session that acts as another person (a review for a colleague). */
+    noteActingSession(sessionId: string, requesterId: string, actorId: string): void;
+    isActingSession(sessionId: string): boolean;
+    /** The audit of the notice a reviewer is sent after something was left on GitHub as them. */
+    noteReviewNotice(notice: ReviewNotice): void;
+    /** In the order written. */
+    reviewNotices(): ReviewNotice[];
+    addAskerFollow(follow: {
+        readonly itemId: string;
+        readonly batchId: string;
+        readonly review: JsonObject;
+        readonly reference: JsonObject;
+        readonly deadline: number;
+    }): void;
+    /** Oldest first. */
+    askerFollows(): AskerFollow[];
+    askerFollowSaid(itemId: string, said: string): void;
+    askerFollowReviewerTold(itemId: string): void;
+    dropAskerFollow(itemId: string): void;
+    /** One notice of this kind per person per `interval` seconds. */
+    claimGithubNotice(userId: string, kind: string, interval: number): boolean;
+    releaseGithubNotice(userId: string, kind: string): void;
+}

package/dist/types/ports/store/idempotency.d.ts

@@ -0,0 +1,21 @@
+/** Work done at most once: activity ids and Claw events (tables `processed`, `event_claims`). */
+export type EventClaim = {
+    readonly state: "claimed";
+    readonly holder: string;
+} | {
+    readonly state: "done" | "busy";
+    readonly holder: "";
+};
+export interface IdempotencyRepository {
+    /** Marks `activityId` processed; true only for the one caller that marked it. */
+    claimProcessed(activityId: string): boolean;
+    /** Claim a Claw event for sending; of any number of copies on the same store, one is sent. */
+    claimEvent(key: string): EventClaim;
+    /** The event reached the chat: every later copy is a duplicate for PROCESSED_TTL_SECONDS. */
+    finishEvent(key: string): void;
+    /** The send failed or was put off: only the claim `holder` took is let go. */
+    releaseEvent(key: string, holder: string): void;
+    seen(activityId: string): boolean;
+    /** Also prunes expired processed ids, pending requests and delivered reports. */
+    markProcessed(activityId: string): void;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * The store port: durable state as repositories grouped by aggregate. One implementation (runtime's SQLite store)
+ * keeps all of them in one database file whose tables and columns are the Python worker's, so either worker can open it.
+ *
+ * Naming: `userId` is the person's stable channel id (the Entra object id on Teams, column `aad_id`); `clawUserId` is
+ * the Claw account a link records; `channelUserId` is the channel's own user id (Teams' `29:` id). Times are epoch
+ * seconds from the injected clock.
+ *
+ * Every method is synchronous: the store is local and each method is one indivisible step, which is what the
+ * check-then-write methods (`redeemPending`, `claimEvent`, `move*` with `onlyFrom`) rely on.
+ */
+import type { ApprovalRepository } from "./approvals.js";
+import type { AssistantButtonRepository, AssistantCardRepository, AssistantMessageRepository } from "./assistant.js";
+import type { FeedbackRepository } from "./feedback.js";
+import type { GithubConfirmationRepository, ReviewDelegationRepository } from "./github.js";
+import type { IdempotencyRepository } from "./idempotency.js";
+import type { LinkRepository } from "./link.js";
+import type { NotifySubscriptionRepository } from "./notify.js";
+import type { ObserveRepository } from "./observe.js";
+import type { OnboardingRepository } from "./onboarding.js";
+import type { ConversationRefRepository, HeldEventRepository, MemberDirectoryRepository, PrefsRepository } from "./people.js";
+import type { RemotePermissionRepository, RemoteSessionNameRepository, RemoteStateRepository } from "./remote.js";
+import type { RepoHistoryRepository, SessionRepository } from "./sessions.js";
+import type { TurnAnswerRepository } from "./turns.js";
+export interface StorePort {
+    readonly links: LinkRepository;
+    readonly references: ConversationRefRepository;
+    readonly prefs: PrefsRepository;
+    readonly held: HeldEventRepository;
+    readonly members: MemberDirectoryRepository;
+    readonly notifySubs: NotifySubscriptionRepository;
+    readonly approvals: ApprovalRepository;
+    readonly observe: ObserveRepository;
+    readonly assistantCards: AssistantCardRepository;
+    readonly assistantButtons: AssistantButtonRepository;
+    readonly assistantMessages: AssistantMessageRepository;
+    readonly remoteState: RemoteStateRepository;
+    readonly remoteSessionNames: RemoteSessionNameRepository;
+    readonly remotePermissions: RemotePermissionRepository;
+    readonly sessions: SessionRepository;
+    readonly repoHistory: RepoHistoryRepository;
+    readonly turns: TurnAnswerRepository;
+    readonly feedback: FeedbackRepository;
+    readonly onboarding: OnboardingRepository;
+    readonly githubConfirmations: GithubConfirmationRepository;
+    readonly reviewDelegation: ReviewDelegationRepository;
+    readonly idempotency: IdempotencyRepository;
+    /** The store's clock, in epoch seconds. */
+    now(): number;
+}
+export type * from "./approvals.js";
+export type * from "./assistant.js";
+export type * from "./feedback.js";
+export type * from "./github.js";
+export type * from "./idempotency.js";
+export type * from "./link.js";
+export type * from "./notify.js";
+export type * from "./observe.js";
+export type * from "./onboarding.js";
+export type * from "./people.js";
+export type * from "./remote.js";
+export type * from "./sessions.js";
+export type * from "./turns.js";
+export { isJsonObject } from "./json.js";
+export * from "./policy.js";

package/dist/types/ports/store/json.d.ts

@@ -0,0 +1,4 @@
+import type { JsonObject } from "../../json.js";
+export type { JsonObject };
+/** A JSON object as opposed to an array or a scalar (what a `*_json` column of an object holds when it is well formed). */
+export declare function isJsonObject(value: unknown): value is JsonObject;

package/dist/types/ports/store/link.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Account links: the SaFE key a person linked from the console with a short `/link` code (tables `links`,
+ * `pending_keys`, `link_attempts`). Keys are encrypted at rest; codes are kept only as a keyed hash.
+ */
+/** How many wrong `/link` codes are allowed in `windowSeconds`: per person, and of all people together. */
+export interface LinkLimits {
+    readonly perUser: number;
+    readonly global: number;
+    readonly windowSeconds: number;
+}
+/**
+ * The answer to a typed code: `invalid` is one answer for wrong, expired and used codes; `limited` (this person has too
+ * many wrong codes in the window) and `global_limit` (everyone together has) refuse even a correct code.
+ */
+export type RedeemOutcome = "ok" | "invalid" | "limited" | "global_limit";
+export interface LinkRepository {
+    /** Hold a key the console just minted under a fresh code and return the code. Nothing a chat sends can create one. */
+    stashPending(key: string): string;
+    /** How long a wrong code counts against its person and everyone. */
+    readonly linkWindowSeconds: number;
+    /** Bind the pending key of `code` to the person who typed it. Spaces are ignored and case does not matter. */
+    redeemPending(userId: string, name: string, code: string, activityId?: string): RedeemOutcome;
+    /** Delete the pending keys nobody redeemed in time and return them, so the caller can revoke them. */
+    takeExpiredPending(): string[];
+    /** The key of exactly this person; there is no fallback to any other key. */
+    getKey(userId: string): string | null;
+    /** Forget the person's link and everything kept for them that a key is needed for. */
+    unlink(userId: string): void;
+    /** The Claw user id of the account the person is linked to. */
+    setClawUserId(userId: string, clawUserId: string): void;
+    /** Linked before the Claw user id was kept (or the lookup failed at link time). */
+    needsClawUserId(userId: string): boolean;
+    clawUserIdOf(userId: string): string | null;
+    /** Every linked person, in a stable order. */
+    linkedUsers(): string[];
+    userForClawUser(clawUserId: string): string | null;
+    /** Every person whose link records this Claw user (one, normally). */
+    usersForClawUser(clawUserId: string): string[];
+}

package/dist/types/ports/store/notify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-person notification subscriptions (tables `notify_subs`, `notify_sub_attempts`). Claw signs a subscription's
+ * events with its own secret and names neither the subscription nor the person, so each person gets a URL with a
+ * random route token of its own, and the token finds the secret (encrypted at rest) and the person.
+ */
+export interface NotifySubscription {
+    readonly route: string;
+    readonly subscriptionId: string;
+}
+export interface NotifyRoute {
+    readonly userId: string;
+    readonly secret: string;
+}
+export interface NotifySubscriptionRepository {
+    saveNotifySub(userId: string, sub: NotifySubscription & {
+        readonly secret: string;
+        readonly typesVersion?: number;
+    }): void;
+    /** Which set of event types the subscription was made or changed for (0: the original two); null: none. */
+    notifyTypesVersion(userId: string): number | null;
+    setNotifyTypesVersion(userId: string, typesVersion: number): void;
+    getNotifySub(userId: string): NotifySubscription | null;
+    /** Null when the route is unknown or its secret cannot be decrypted. */
+    notifySubByRoute(route: string): NotifyRoute | null;
+    forgetNotifySub(userId: string): void;
+    /** True (and the attempt is recorded) when none was made in the last `minInterval` seconds. */
+    claimNotifyAttempt(userId: string, minInterval: number): boolean;
+}

package/dist/types/ports/store/observe.d.ts

@@ -0,0 +1,53 @@
+/** Group chats the assistant observes, and the suggestions shown on /board (tables `observed_groups`, `observe_cards`). */
+import type { JsonObject } from "./json.js";
+export interface GroupObserver {
+    readonly userId: string;
+    readonly scope: string;
+}
+export interface ObservedGroup {
+    readonly conversationId: string;
+    readonly scope: string;
+    readonly name: string;
+    /** Observing is on now. */
+    readonly on: boolean;
+}
+export type ObserveCardState = "open" | "busy" | "accepted" | "dismissed" | "unsure" | (string & {});
+export interface ObserveCard {
+    readonly cardId: string;
+    readonly userId: string;
+    readonly conversationId: string;
+    readonly runId: string;
+    readonly seq: number;
+    readonly tool: string;
+    readonly args: string;
+    readonly message: string;
+    readonly state: ObserveCardState;
+}
+export interface NewObserveCard {
+    readonly userId: string;
+    readonly conversationId: string;
+    readonly runId: string;
+    readonly seq: number;
+    readonly tool: string;
+    readonly args: string;
+    readonly message: string;
+}
+export interface ObserveRepository {
+    /** `/observe on`: one observer per group, the last to turn it on. `name` is kept to 200 characters. */
+    observeGroup(conversationId: string, observer: GroupObserver & {
+        readonly reference: JsonObject;
+        readonly name?: string;
+    }): void;
+    /** `/observe off`: returns whose observer it was, or null when it was not on. The row stays for /board. */
+    unobserveGroup(conversationId: string): string | null;
+    groupObserver(conversationId: string): GroupObserver | null;
+    /** Every group this person turned observing on in, newest first. */
+    observedBy(userId: string): ObservedGroup[];
+    observedReference(conversationId: string): JsonObject | null;
+    addObserveCard(card: NewObserveCard): string;
+    getObserveCard(cardId: string): ObserveCard | null;
+    /** Accepted, dismissed or unsure already (on any card of it): not offered again. */
+    observeSuggestionSettled(userId: string, runId: string, seq: number): boolean;
+    /** With `onlyFrom`, of two presses on one suggestion only one moves it; 'busy' also refuses a suggestion already in hand. */
+    moveObserveCard(cardId: string, state: ObserveCardState, onlyFrom?: ObserveCardState): boolean;
+}