@primusclaw/personal-agent 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,49 @@
+/** Group onboarding of a member who has not linked yet (tables `onboarding_cards`, `onboarding_dms`,
+ * `pending_requests`). */
+import type { JsonObject } from "./json.js";
+export interface OnboardingCard {
+    readonly promptId: string;
+    /** The member the card is for: the only one who may press its button. */
+    readonly userId: string;
+    /** The group chat's conversation id. */
+    readonly scope: string;
+    /** Their channel id (what a mention and a 1:1 conversation need). */
+    readonly channelUserId: string;
+    readonly name: string;
+    readonly createdAt: number;
+}
+export interface PendingRequest {
+    readonly userId: string;
+    /** The group chat the request was made in. */
+    readonly scope: string;
+    readonly messageId: string;
+    readonly text: string;
+    /** Where to post in that chat. */
+    readonly reference: JsonObject;
+    readonly createdAt: number;
+    /** The message(s) it quoted, as text for the model. */
+    readonly quote: string;
+    /** What it said with the addresses behind its links; '' when that is `text`. */
+    readonly sent: string;
+}
+export type NewPendingRequest = Omit<PendingRequest, "createdAt" | "quote" | "sent"> & {
+    readonly quote?: string;
+    readonly sent?: string;
+};
+export interface OnboardingRepository {
+    /** One card per person per group per day: the new card's id, or null when one went out within the day. */
+    claimOnboardingCard(userId: string, scope: string, member: {
+        readonly channelUserId: string;
+        readonly name: string;
+    }): string | null;
+    /** The claimed card never reached the chat: the allowance is not spent. */
+    releaseOnboardingCard(promptId: string): void;
+    getOnboardingCard(promptId: string): OnboardingCard | null;
+    /** One proactive DM per person per day. */
+    claimOnboardingDm(userId: string): boolean;
+    releaseOnboardingDm(userId: string): void;
+    /** Kept for PENDING_REQUEST_TTL_SECONDS; a newer request replaces it. */
+    savePendingRequest(request: NewPendingRequest): void;
+    /** Once: gone after this call; null when none or expired. */
+    takePendingRequest(userId: string): PendingRequest | null;
+}

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

@@ -0,0 +1,77 @@
+/** Where and how to reach a person, and what is known of them (tables `conversation_refs`, `user_prefs`, `held_events`,
+ * `teams_users`, `personal_clicks`). */
+import type { JsonObject } from "./json.js";
+export interface Prefs {
+    readonly timezone: string;
+    readonly quietEnabled: boolean;
+    readonly quietStart: string;
+    readonly quietEnd: string;
+    /** Epoch seconds notices are paused until; null: not paused. */
+    readonly pausedUntil: number | null;
+    readonly briefTriggerId: string | null;
+    /** 'zh' / 'en' the person is answered in; '' not known yet. */
+    readonly lang: string;
+    /** They said which (`/lang`): what they write changes nothing. */
+    readonly langSet: boolean;
+    /** 'card' | 'chat' as the person set it (`/agent mode`); '' not said. */
+    readonly remoteWindow: string;
+}
+export interface ConversationRefRepository {
+    /** Keep where to post to this person unprompted (the reference's activityId is dropped). */
+    saveReference(userId: string, reference: JsonObject): void;
+    getReference(userId: string): JsonObject | null;
+    /** When the person last wrote in their 1:1 chat or pressed a button there. */
+    lastInboundAt(userId: string): number | null;
+}
+export interface PrefsRepository {
+    getPrefs(userId: string): Prefs;
+    getTimezone(userId: string): string;
+    setTimezone(userId: string, timezone: string): void;
+    /** A (start, end) wall-clock window in the person's time zone, or null for no quiet hours. */
+    setQuiet(userId: string, window: readonly [string, string] | null): void;
+    setPausedUntil(userId: string, until: number | null): void;
+    /** Ignored unless `window` is 'card' or 'chat'. */
+    setRemoteWindowPref(userId: string, window: string): void;
+    setBriefTrigger(userId: string, triggerId: string | null): void;
+    /** `said` false (`/lang auto`): `lang` is only a starting point that `learnLang` changes again. */
+    setLang(userId: string, lang: string, said?: boolean): void;
+    /** The language a message was written in: kept unless the person said which. */
+    learnLang(userId: string, lang: string): void;
+}
+/** Notices held back by quiet hours or /pause. */
+export interface HeldEventRepository {
+    /** `event.event_id` identifies it; the newest MAX_HELD_PER_USER per person are kept, for HELD_TTL_SECONDS. */
+    holdEvent(userId: string, event: JsonObject): void;
+    usersWithHeld(): string[];
+    /** Remove and return the person's held events, oldest first, at once. */
+    takeHeld(userId: string): JsonObject[];
+}
+/** A person as the channel's member list reads (`id` the channel id, `objectId` the person id). */
+export interface KnownMember {
+    readonly id: string;
+    readonly objectId: string;
+    readonly name: string;
+    readonly email?: string;
+}
+/** A member entry as a group's member list gives it. */
+export interface MemberListEntry {
+    readonly id?: unknown;
+    readonly email?: unknown;
+    readonly userPrincipalName?: unknown;
+}
+/** Which person a channel user id belongs to, as their own messages say. */
+export interface MemberDirectoryRepository {
+    /** `email` '' keeps the address already known. */
+    rememberMember(channelUserId: string, userId: string, name: string, email?: string): void;
+    /** Addresses from a member list, kept only for people already known. */
+    rememberMemberEmails(members: readonly MemberListEntry[]): void;
+    /** Everyone seen, newest first. */
+    knownMembers(limit?: number): KnownMember[];
+    userForChannelId(channelUserId: string): string | null;
+    /** The channel id this person last wrote with. */
+    channelIdOf(userId: string): string | null;
+    memberName(userId: string): string | null;
+    /** A card click of theirs arrived from their 1:1 chat (the app is installed for them). */
+    notePersonalClick(userId: string): void;
+    clickedPersonally(userId: string): boolean;
+}

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

@@ -0,0 +1,60 @@
+/** How long a `/link` code minted by the console can be redeemed. */
+export declare const LINK_CODE_TTL_SECONDS: number;
+export declare const CODE_LENGTH = 8;
+/** The alphabet a link code is drawn from: no 0/O/1/I. */
+export declare const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/** Wrong codes per user in the window (TEAMS_LINK_MAX_FAILURES_PER_USER). */
+export declare const MAX_FAILED_ATTEMPTS = 5;
+/** Wrong codes of all users together in the window (TEAMS_LINK_MAX_FAILURES_GLOBAL). */
+export declare const MAX_FAILED_ATTEMPTS_GLOBAL = 100;
+/** TEAMS_LINK_ATTEMPT_WINDOW_SECONDS. */
+export declare const ATTEMPT_WINDOW_SECONDS: number;
+/** An action is carried out for an assistant message this young, at most. */
+export declare const ASSISTANT_MESSAGE_KEEP_SECONDS: number;
+/** A held write's card: Claw keeps the confirmation for a day; a press after that is told so. */
+export declare const CONFIRM_CARD_KEEP_SECONDS: number;
+export declare const PROCESSED_TTL_SECONDS: number;
+/** A Claw event being sent is claimed this long; past it the claim is taken to have died with its process. */
+export declare const EVENT_CLAIM_LEASE_SECONDS: number;
+/** "What went wrong?" waits this long for the user's next message. */
+export declare const FEEDBACK_ASK_TTL_SECONDS: number;
+/** The "include my last question and answer" buttons work this long. */
+export declare const FEEDBACK_OFFER_TTL_SECONDS: number;
+/** An offer row is kept this long. */
+export declare const FEEDBACK_OFFER_KEEP_SECONDS: number;
+/** The "Report a problem" button under a failed message works this long. */
+export declare const FEEDBACK_PROMPT_TTL_SECONDS: number;
+/** Same user + same session within this long: a comment on the same issue. */
+export declare const FEEDBACK_DEDUPE_SECONDS: number;
+/** Delivered reports are kept this long (undelivered ones are never dropped). */
+export declare const FEEDBACK_KEEP_SECONDS: number;
+/** One onboarding card per person per group chat, and one proactive DM per person, in this long. */
+export declare const ONBOARDING_INTERVAL_SECONDS: number;
+/** A group request from someone who is not linked yet waits this long for them to link. */
+export declare const PENDING_REQUEST_TTL_SECONDS: number;
+/** A message a turn answered drops its run's card this long. */
+export declare const ANSWERED_MESSAGE_KEEP_SECONDS: number;
+/** A remote permission row is kept this long after it ran out (stale-click message). */
+export declare const REMOTE_PERMISSION_KEEP_SECONDS: number;
+/** A card for a work item answers its buttons this long; after that /board shows the item again. */
+export declare const ASSISTANT_CARD_KEEP_SECONDS: number;
+export declare const DEFAULT_TIMEZONE = "Asia/Shanghai";
+export declare const DEFAULT_QUIET: readonly [string, string];
+/** 9999-12-31: "until /resume". */
+export declare const PAUSE_FOREVER = 253402300799;
+export declare const MAX_HELD_PER_USER = 100;
+export declare const HELD_TTL_SECONDS: number;
+/** How long an approval row is kept after it expired, for the stale-click message. */
+export declare const APPROVAL_TTL_SECONDS: number;
+/** How long a review session is remembered as one that acts as a user. */
+export declare const ACTING_SESSION_KEEP_SECONDS: number;
+/** The repositories /repo remembers per user (and lists). */
+export declare const RECENT_REPOS = 5;
+/** "My next message is for this repository" is forgotten after this. */
+export declare const PENDING_REPO_TTL_SECONDS: number;
+/** The sessions /sessions lists. */
+export declare const SESSION_LIST = 5;
+/** The sessions a chat remembers per user: more than are listed, so a deletion in Claw leaves some. */
+export declare const SESSION_HISTORY_KEEP = 20;
+/** The session cards of one remote attachment remembered for quote replies. */
+export declare const WINDOW_CARDS_KEPT = 8;

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

@@ -0,0 +1,114 @@
+/** Remote agents: which session a chat is attached to, how far it has read, and the permission cards it showed
+ * (tables `remote_state`, `remote_session_names`, `remote_permissions`). */
+/** 'card': the chat box goes to the assistant and the session card's input to the session; 'chat': all to the session. */
+export type ChatBox = "card" | "chat";
+export interface RemoteState {
+    /** null: not attached. */
+    readonly sessionId: string | null;
+    readonly connectorId: string;
+    readonly agentId: string;
+    readonly agentLabel: string;
+    readonly host: string;
+    readonly cwd: string;
+    /** Id of the last event of the session handled ('' none). */
+    readonly cursor: string;
+    /** A prompt was sent and its turn end has not been seen. */
+    readonly turnOpen: boolean;
+    readonly mode: string;
+    readonly modes: readonly string[];
+    /** Session ids of the last /agent sessions, in the order shown. */
+    readonly listing: readonly string[];
+    /** The session does not ask before a step; null: not said. */
+    readonly unattended: boolean | null;
+    /** mode id -> whether selecting it makes the session unattended. */
+    readonly modeFlags: Readonly<Record<string, boolean>>;
+    readonly statusCard: string;
+    readonly attachedAt: number;
+    readonly conversation: string;
+    readonly conversationRef: string;
+    readonly window: ChatBox | (string & {});
+    readonly windowCards: readonly string[];
+}
+export interface RemoteAttachment {
+    readonly sessionId: string;
+    readonly connectorId: string;
+    readonly agentId: string;
+    readonly agentLabel: string;
+    readonly host: string;
+    readonly cwd: string;
+    readonly cursor?: string;
+    readonly mode?: string;
+    readonly modes?: readonly string[] | null;
+    readonly unattended?: boolean | null;
+    readonly modeFlags?: Readonly<Record<string, boolean>> | null;
+    readonly conversation?: string;
+    readonly conversationRef?: string;
+    readonly window?: string;
+}
+/** What the agent said about its permission modes; an absent part stays as it was. */
+export interface RemoteModes {
+    readonly mode?: string | null;
+    readonly modes?: readonly string[] | null;
+    readonly unattended?: boolean | null;
+    readonly modeFlags?: Readonly<Record<string, boolean>> | null;
+}
+export interface RemoteSessionName {
+    readonly title: string;
+    readonly conversationRef: string;
+}
+export interface RemoteStateRepository {
+    getRemote(chatKey: string): RemoteState | null;
+    remoteAttachedUsers(): string[];
+    attachedRemote(chatKey: string): RemoteState | null;
+    /** The last listing and status card survive an attach. */
+    attachRemote(chatKey: string, attachment: RemoteAttachment): void;
+    setRemoteWindow(chatKey: string, window: string): void;
+    /** Remember a replaced session card (the last WINDOW_CARDS_KEPT). */
+    noteWindowCard(chatKey: string, cardId: string, kept?: number): void;
+    detachRemote(chatKey: string): void;
+    /** Only forward, and only for the attached session; a non-numeric cursor is ignored. */
+    setRemoteCursor(chatKey: string, sessionId: string, cursor: string): void;
+    setRemoteTurn(chatKey: string, sessionId: string, isOpen: boolean): void;
+    setRemoteModes(chatKey: string, sessionId: string, modes: RemoteModes): void;
+    setRemoteStatusCard(chatKey: string, cardId: string): void;
+    setRemoteListing(chatKey: string, sessionIds: readonly string[]): void;
+}
+export interface RemoteSessionNameRepository {
+    nameRemoteSession(userId: string, sessionId: string, name?: Partial<RemoteSessionName>): void;
+    /** Only a session with no title yet gets one. */
+    titleRemoteSession(sessionId: string, title: string): void;
+    setRemoteSessionAcp(sessionId: string, acpSessionId: string): void;
+    remoteSessionAcps(userId: string): Map<string, string>;
+    remoteSessionNames(userId: string): Map<string, RemoteSessionName>;
+}
+export type RemotePermissionState = "pending" | "sending" | "decided" | "expired" | (string & {});
+export interface RemotePermission {
+    readonly sessionId: string;
+    readonly actionId: string;
+    readonly userId: string;
+    readonly tool: string;
+    /** [{optionId, name, kind}] exactly as the agent offered them. */
+    readonly options: readonly unknown[];
+    readonly expiresAt: number;
+    readonly state: RemotePermissionState;
+}
+export interface NewRemotePermission {
+    readonly userId: string;
+    readonly sessionId: string;
+    readonly actionId: string;
+    readonly tool: string;
+    readonly options: readonly unknown[];
+    readonly expiresAt: number;
+}
+export interface RemotePermissionRepository {
+    /** Recorded before it is shown; false when this request already has a row. */
+    saveRemotePermission(permission: NewRemotePermission): boolean;
+    getRemotePermission(sessionId: string, actionId: string): RemotePermission | null;
+    /** Pending and not run out, oldest first. */
+    pendingRemotePermissions(userId: string, sessionId: string): RemotePermission[];
+    waitingRemoteSessions(userId: string): Set<string>;
+    forgetRemotePermission(sessionId: string, actionId: string): void;
+    closeRemotePermission(sessionId: string, actionId: string, state: RemotePermissionState, options?: {
+        readonly onlyIfPending?: boolean;
+    }): boolean;
+}

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

@@ -0,0 +1,59 @@
+/** Which Claw session a chat uses, and what /repo and /sessions remember (tables `sessions`, `recent_repos`,
+ * `pending_repo`, `session_history`). Scope '' is the 1:1 chat; a group chat's conversation id is its own scope. */
+export interface ChatSession {
+    readonly sessionId: string;
+    /** The plugin it was created with ('' none). */
+    readonly pluginId: string;
+    /** The model it is known to have been given ('' Claw's default). */
+    readonly model: string;
+    /** Created shared (no memory in it). */
+    readonly shared: boolean;
+}
+export interface SessionRepository {
+    getSession(userId: string, scope?: string): string | null;
+    getSessionPlugin(userId: string, scope?: string): string;
+    getSessionModel(userId: string, scope?: string): string;
+    getSessionShared(userId: string, scope?: string): boolean;
+    setSession(userId: string, session: Partial<ChatSession> & {
+        readonly sessionId: string;
+    }, scope?: string): void;
+    clearSession(userId: string, scope?: string): void;
+}
+export interface RepoChoice {
+    /** "owner/name" */
+    readonly repo: string;
+    /** '' the default branch. */
+    readonly branch: string;
+}
+export interface HistorySession {
+    readonly sessionId: string;
+    /** What the session was started with ('' when never seen to start). */
+    readonly title: string;
+    readonly repo: string;
+    readonly branch: string;
+    /** When this chat last used it. */
+    readonly lastAt: number;
+}
+export interface NotedSession {
+    readonly title?: string;
+    readonly repo?: string;
+    readonly branch?: string;
+}
+export interface RepoHistoryRepository {
+    /** The newest of the person's RECENT_REPOS (same repository, compared without case, and branch: one entry). */
+    touchRecentRepo(userId: string, choice: RepoChoice): void;
+    /** Newest first. */
+    recentRepos(userId: string): RepoChoice[];
+    /** The person's next new session is bound to this repository. */
+    setPendingRepo(userId: string, choice: RepoChoice): void;
+    /** Null when none, or older than PENDING_REPO_TTL_SECONDS. */
+    getPendingRepo(userId: string): RepoChoice | null;
+    clearPendingRepo(userId: string): void;
+    /** The chat used `sessionId` now; a known session keeps its title and repository unless it had none. */
+    noteSession(userId: string, sessionId: string, seen?: NotedSession): void;
+    /** Newest first. */
+    sessionHistory(userId: string, limit?: number): HistorySession[];
+    forgetSession(userId: string, sessionId: string): void;
+    /** Everything /repo and /sessions remember about the person. */
+    forgetRepos(userId: string): void;
+}

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

@@ -0,0 +1,30 @@
+/** Chat turns that answer in the chat, so the run's own notification card is redundant (tables `turn_answers`,
+ * `answered_messages`). */
+export type AnsweredInChat = "delivered" | "running" | "lost";
+export interface FinishedRun {
+    /** When the run finished (Claw's notification). */
+    readonly finishedAt: number;
+    /** A turn this process started and younger than this is still running. */
+    readonly runningMax: number;
+    /** Clock skew allowed between the delivery and the run's end. */
+    readonly slack: number;
+    /** The run's chat message, when Claw names it. */
+    readonly messageId?: string;
+}
+export interface TurnAnswerRepository {
+    turnStarted(sessionId: string, turn?: {
+        readonly prompt?: string;
+        readonly messageId?: string;
+        readonly turnId?: string;
+    }): void;
+    /** With `turnId`, the row is updated only while it is still that turn's. */
+    turnDelivered(sessionId: string, turn?: {
+        readonly messageId?: string;
+        readonly turnId?: string;
+    }): void;
+    turnNotDelivered(sessionId: string, turnId?: string): void;
+    /** Whether a chat turn answered the run of this session that finished at `run.finishedAt`; null if none. */
+    answeredInChat(sessionId: string, run: FinishedRun): AnsweredInChat | null;
+    /** What was asked in the turn that started the run ('' when no chat turn did). */
+    turnPrompt(sessionId: string, finishedAt: number): string;
+}