soulnet-dsh 0.1.0

package/lib/types/friend-settings.d.ts

@@ -0,0 +1,41 @@
+import { type ReplyTier } from './policy.ts';
+export declare const FRIEND_SETTINGS_FILE = "dsh-friends.json";
+export declare const PROTOCOL_FILE = "protocol.md";
+export interface FriendSettings {
+    readonly tier?: ReplyTier;
+}
+/** In-memory copy of dsh-friends.json with write-through. */
+export declare class FriendSettingsStore {
+    private readonly path;
+    private data;
+    private loaded;
+    constructor(path: string);
+    static at(a2aDir: string): FriendSettingsStore;
+    load(): Promise<void>;
+    get isLoaded(): boolean;
+    get(fp: string): FriendSettings;
+    /** Tier of a friend, or `fallback` (the global default) when none is stored. */
+    tier(fp: string, fallback: ReplyTier): ReplyTier;
+    /** Every stored entry (fp → settings). */
+    all(): Readonly<Record<string, FriendSettings>>;
+    /** Patch one friend's settings; an explicit `tier: undefined` clears the stored tier (back to the global default). */
+    set(fp: string, patch: {
+        tier?: ReplyTier | undefined;
+    }): Promise<FriendSettings>;
+    remove(fp: string): Promise<void>;
+}
+/**
+ * The global diplomacy protocol file. `read()` is synchronous and cached by
+ * mtime so a prompt-variable provider can call it on every assembly; `write()`
+ * replaces the file (and the cache).
+ */
+export declare class ProtocolFile {
+    readonly path: string;
+    private cache;
+    constructor(path: string);
+    static at(a2aDir: string): ProtocolFile;
+    /** Current text; `''` when the file does not exist yet (the peer writes it with the identity). */
+    read(): string;
+    exists(): boolean;
+    write(text: string): void;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * soulnet-dsh — host root entry = the `soulmirror-network` plugin.
+ *
+ * Provides `ctx.soulmirror` (NetworkClient: the `soulnet` light peer by
+ * default, the in-memory fake on request) and `ctx.soulmirrorHome`, registers
+ * the `soulmirror` user-settings namespace and mounts the browser-facing HTTP
+ * API (./api). The bare package name is also what dsh's client-module scan keys
+ * on, so this entry carries the browser bundle declaration (package.json
+ * `dsh.client` + the `./client` export).
+ *
+ * Host side rule: NO @deepseek-ai VALUE imports into the harness instance
+ * (types only; the one vendored library we do import, schemastery, is inlined).
+ * A linked (`dsh plugin add ./packages/dsh`) package resolves bare specifiers
+ * from its own real path, where the harness packages are not installed; and a
+ * second copy of cordis/dsh-tools would be a different runtime instance anyway.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { NetworkClient } from './network/types.ts';
+import { type SoulmirrorSettings } from './settings.ts';
+export type * from './network/types.ts';
+export type * from './events.ts';
+export { SOULMIRROR_PLUGIN, RELAY_FORM } from './events.ts';
+export { SETTINGS_NAMESPACE } from './settings.ts';
+export type { SoulmirrorSettings } from './settings.ts';
+/** Live view of the `soulmirror` settings (the alter fields apply without a restart). */
+export interface SoulmirrorConfig {
+    current(): SoulmirrorSettings;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** SoulMirror network client (identity / card / friends / send / subscribe). */
+        soulmirror: NetworkClient;
+        /** Backend data directory (`a2a/` underneath: identity.json, friends.yaml, conversations/ …; same layout as ~/.soulmirror/a2a). */
+        soulmirrorHome: string;
+        /** Live settings: `defaultTier` / `autoReplyPerHour` / `directSend` are read per use; connection fields apply on reload. */
+        soulmirrorConfig: SoulmirrorConfig;
+    }
+}
+/** Composition entry config; every field is also a user setting (namespace `soulmirror`). */
+export type Config = Partial<SoulmirrorSettings>;
+export declare const name = "soulmirror-network";
+export declare const inject: string[];
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/types/network/fake.d.ts

@@ -0,0 +1,10 @@
+import { type Friend, type NetworkClient, type PendingRequest } from './types.ts';
+export declare const FAKE_FRIENDS: readonly Friend[];
+export declare const FAKE_PENDING: readonly PendingRequest[];
+export interface FakeOptions {
+    /** Delay before the canned inbound message fires after the first subscribe (ms); negative = never. */
+    readonly firstInboundDelayMs?: number;
+    /** Start without an identity (first-run onboarding path). Default: identity present. */
+    readonly noIdentity?: boolean;
+}
+export declare function createFakeNetworkClient(options?: FakeOptions): NetworkClient;

package/lib/types/network/jsonrpc.d.ts

@@ -0,0 +1,52 @@
+import type { Readable, Writable } from 'node:stream';
+export interface JsonRpcErrorShape {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+/** A JSON-RPC error response, or a transport failure (code -32099 family). */
+export declare class JsonRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    readonly name = "JsonRpcError";
+    constructor(message: string, code: number, data?: unknown | undefined);
+}
+/** Transport-level code: the endpoint closed before the response arrived. */
+export declare const JSONRPC_CLOSED = -32099;
+/** Transport-level code: no response within the request timeout. */
+export declare const JSONRPC_TIMEOUT = -32098;
+export interface JsonRpcNotification {
+    readonly method: string;
+    readonly params: unknown;
+}
+export interface JsonRpcEndpointOptions {
+    /** Default per-request timeout in ms (0 = none). */
+    readonly timeoutMs?: number;
+    readonly onNotification?: (notification: JsonRpcNotification) => void;
+    /** Unparseable or malformed inbound lines (never thrown). */
+    readonly onProtocolError?: (error: Error, line: string) => void;
+    /** The read side ended (EOF/error); every pending request is rejected first. */
+    readonly onClose?: (error?: Error) => void;
+}
+export declare class JsonRpcEndpoint {
+    private readonly input;
+    private readonly output;
+    private readonly options;
+    private readonly pending;
+    private readonly reader;
+    private nextId;
+    private closed;
+    constructor(input: Readable, output: Writable, options?: JsonRpcEndpointOptions);
+    get isClosed(): boolean;
+    /** Send a request and await its result; rejects with {@link JsonRpcError}. */
+    request(method: string, params?: unknown, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /** Fire-and-forget request without an id (no response expected). */
+    notify(method: string, params?: unknown): void;
+    /** Reject every pending request and stop reading. Idempotent. */
+    close(error?: Error): void;
+    private write;
+    private handleLine;
+}

package/lib/types/network/send.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Send through the peer and read the archived entry back (shared by the
+ * browser API's direct send and the alter's `soulmirror_send_message` tool):
+ * the peer answers `seq` / `status`; the archive line carries the exact `ts`
+ * and `auto` flag, which the SoulMirror page needs to reconcile its
+ * optimistic bubble or to paint the alter's send. Falls back to a constructed
+ * entry when the read-back misses.
+ */
+import type { Fingerprint } from '../events.ts';
+import type { ConversationEntry, NetworkClient, SendOptions } from './types.ts';
+export interface SentEntry {
+    readonly entry: ConversationEntry;
+    readonly receipt: {
+        id: string;
+        seq?: number;
+        status: string;
+    };
+}
+export declare function sendAndArchive(client: NetworkClient, fp: Fingerprint, body: string, options?: SendOptions): Promise<SentEntry>;

package/lib/types/network/soulnet.d.ts

@@ -0,0 +1,123 @@
+/**
+ * `soulnet` backend: spawns the soulnet light peer (Go, ../cmd/soulnet) and
+ * drives it over line-delimited JSON-RPC 2.0 on stdio (protocol: cmd/soulnet/
+ * README.md, `initialize.protocol === "soulnet/1"`).
+ *
+ *  - request/response by id, notifications → `subscribe` listeners;
+ *  - the process is restarted with exponential backoff when it dies;
+ *  - `dispose()` sends `shutdown`, then kills the process if it lingers;
+ *  - calls issued while the peer is (re)starting wait for it up to the request
+ *    timeout instead of failing immediately.
+ *
+ * Binary lookup (`resolveSoulnetBinary` / `locateSoulnetBinary`), in order:
+ *   1. the explicit `peerBinary` setting (absolute path, or a bare name looked up on PATH);
+ *   2. the platform package `soulnet-peer-<os>-<arch>` installed next to
+ *      this plugin as an optional dependency (`require.resolve('<pkg>/package.json')`
+ *      from this file and from its realpath, so pnpm's symlinked virtual store and
+ *      the hoisted layout both work) -> `<pkg>/bin/soulnet[.exe]`;
+ *   3. `soulnet` on PATH;
+ *   4. `<plugin dir>/bin/soulnet[.exe]` (a hand-dropped binary for development).
+ * The winner and its source are reported in `BackendStatus.binary` / `binarySource`.
+ */
+import { type ChildProcess } from 'node:child_process';
+import { type Friend, type NetworkClient, type PendingRequest } from './types.ts';
+export declare const DEFAULT_RELAY = "https://relay.startupworld.cn";
+export declare const SOULNET_PROTOCOL = "soulnet/1";
+export type SoulnetLogger = (level: 'info' | 'warn' | 'error', message: string) => void;
+export interface SoulnetSpawnRequest {
+    readonly binary: string;
+    readonly args: readonly string[];
+}
+export interface SoulnetClientOptions {
+    /** Data directory passed as `--home` (`a2a/` lives underneath). */
+    readonly home: string;
+    /** Relay URL passed as `--relay` (only used when the identity is created). */
+    readonly relay?: string;
+    /** Create the identity with this name on first start (`initialize {name}`); empty = wait for the host. */
+    readonly displayName?: string;
+    /** Explicit binary path; when absent {@link resolveSoulnetBinary} runs. */
+    readonly peerBinary?: string;
+    /** Per-request timeout (default 30 s; `message.send` with the relay down can take a while). */
+    readonly requestTimeoutMs?: number;
+    /** Restart backoff (ms). Defaults: 500 → ×2 → max 30 000. */
+    readonly backoff?: {
+        readonly initialMs?: number;
+        readonly maxMs?: number;
+        readonly factor?: number;
+    };
+    /** Test seam: replace `child_process.spawn`. */
+    readonly spawn?: (request: SoulnetSpawnRequest) => ChildProcess;
+    readonly logger?: SoulnetLogger;
+    /** Extra env for the child (merged over process.env). */
+    readonly env?: Record<string, string>;
+}
+/** Default home: `$SOULNET_HOME`, else `~/.soulnet` (same rule as the binary itself). */
+export declare function defaultSoulnetHome(env?: NodeJS.ProcessEnv): string;
+/** Where the binary came from (reported in `BackendStatus.binarySource`). */
+export type SoulnetBinarySource = 'setting' | 'platform-package' | 'path' | 'plugin-bin';
+export interface SoulnetBinaryLocation {
+    readonly path: string;
+    readonly source: SoulnetBinarySource;
+}
+/** npm scope of the platform packages that ship the binary. */
+/** Prefix of the per-platform binary packages on npm (`soulnet-peer-<os>-<arch>`). */
+export declare const PLATFORM_PACKAGE_PREFIX = "soulnet-peer-";
+/** The `<os>-<arch>` pairs a platform package exists for (must match dsh/packages/soulnet-*). */
+export declare const PLATFORM_PACKAGE_TARGETS: readonly string[];
+/** `soulnet-peer-<os>-<arch>` for a supported pair, else `undefined`. */
+export declare function platformPackageName(platform?: NodeJS.Platform, arch?: string): string | undefined;
+export interface ResolveSoulnetBinaryOptions {
+    /** `process.arch` by default. */
+    readonly arch?: string;
+    /** Test seam: package name -> installed package directory (default: `require.resolve` next to this file). */
+    readonly resolvePackageDir?: (name: string) => string | undefined;
+}
+/**
+ * Find the `soulnet` binary (order documented at the top of this file) and say
+ * where it came from. `undefined` when nothing was found (the caller reports a
+ * clear error).
+ */
+export declare function locateSoulnetBinary(explicit: string | undefined, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, options?: ResolveSoulnetBinaryOptions): SoulnetBinaryLocation | undefined;
+/** Path-only form of {@link locateSoulnetBinary}. */
+export declare function resolveSoulnetBinary(explicit: string | undefined, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, options?: ResolveSoulnetBinaryOptions): string | undefined;
+interface WireCard {
+    name?: string;
+}
+interface WireMessage {
+    id?: string;
+    from?: string;
+    to?: string;
+    ts?: string;
+    type?: string;
+    body?: string;
+    auto?: boolean;
+    artifact_name?: string;
+    card?: WireCard;
+}
+interface WireFriend {
+    fingerprint?: string;
+    note?: string;
+    protocol?: string;
+    card?: WireCard;
+    added_at?: string;
+    count?: number;
+    unread?: number;
+    last?: WireMessage;
+    typing?: boolean;
+}
+interface WirePending {
+    id?: string;
+    peer?: string;
+    incoming?: WireMessage;
+    created_at?: string;
+}
+export declare function friendFromWire(w: WireFriend): Friend;
+export declare function pendingFromWire(w: WirePending): PendingRequest;
+/**
+ * Create the soulnet-backed NetworkClient. The process is spawned lazily on
+ * the first call or on `start()`; `dispose()` stops it.
+ */
+export declare function createSoulnetNetworkClient(options: SoulnetClientOptions): NetworkClient & {
+    start(): void;
+};
+export {};

package/lib/types/network/types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * NetworkClient — the ONE interface every SoulMirror network backend
+ * implements (architecture spec §2). Host plugins only ever see this
+ * interface. Two implementations ship:
+ *
+ *  - `soulnet` (default): spawns the `soulnet` light peer (Go, ../cmd/soulnet)
+ *    and talks line-delimited JSON-RPC 2.0 over its stdio (./soulnet.ts);
+ *  - `fake`: an in-memory backend for tests and UI work (./fake.ts).
+ */
+import type { A2AMessageId, Fingerprint } from '../events.ts';
+export type BackendKind = 'fake' | 'soulnet';
+export interface Identity {
+    readonly fp: Fingerprint;
+    readonly name: string;
+    /** Card URI (`soulmirror://card?...`) others paste to add us. */
+    readonly cardUri: string;
+    /** ISO timestamp of identity creation when known. */
+    readonly createdAt?: string;
+}
+export interface Friend {
+    readonly fp: Fingerprint;
+    /** Display name: the local note when set, else the name on the peer's card. */
+    readonly name: string;
+    /** Local note (SoulMirror "note"); undefined when none was set. */
+    readonly remark?: string;
+    /** Name the peer declared on its card. */
+    readonly cardName?: string;
+    /** Per-friend diplomacy protocol override (friends.yaml `protocol`); undefined/empty = the global protocol applies. */
+    readonly protocol?: string;
+    readonly online?: boolean;
+    /** Unread inbound messages (sent by the peer after our read cursor). */
+    readonly unread: number;
+    /** Total archived conversation entries. */
+    readonly count: number;
+    /** Timestamp (ms) of the last archived entry, when any. */
+    readonly lastTs?: number;
+    /** Preview of the last archived entry body. */
+    readonly lastBody?: string;
+    /** The peer is signalling "busy"/typing right now. */
+    readonly typing?: boolean;
+    readonly addedAt?: string;
+}
+export interface PendingRequest {
+    /** Request id (= the request message id); what `friends.accept/reject` take. */
+    readonly id: string;
+    readonly fp: Fingerprint;
+    /** Name on the requester's card. */
+    readonly name: string;
+    /** Greeting text sent with the request. */
+    readonly greeting: string;
+    readonly createdAt?: string;
+}
+export interface InboundMessage {
+    readonly id: A2AMessageId;
+    readonly from: Fingerprint;
+    /** Display name of the sender as known when the message arrived. */
+    readonly name: string;
+    readonly body: string;
+    /** Unix epoch ms. */
+    readonly ts: number;
+    /** 1-based line number in the peer's conversation archive, when archived. */
+    readonly seq?: number;
+    readonly auto?: true;
+    /** A2A message type (`text`, `app_share`, …). */
+    readonly type?: string;
+    /** Absolute path of an attachment written to disk, when any. */
+    readonly artifactPath?: string;
+    readonly artifactName?: string;
+}
+export interface ConversationEntry {
+    readonly seq: number;
+    readonly dir: 'in' | 'out';
+    readonly id: A2AMessageId;
+    readonly body: string;
+    readonly ts: number;
+    readonly type?: string;
+    readonly auto?: true;
+    /** Outbound only: `sent` | `queued` | `error`. */
+    readonly status?: string;
+    readonly artifactName?: string;
+}
+/** Optional parts of one send. */
+export interface SendOptions {
+    /** Absolute path of one local file to attach. */
+    readonly file?: string;
+    /** Mark the message as the alter's automatic reply (A2A `auto` flag; the receiver's loop guard). */
+    readonly auto?: boolean;
+}
+export interface SendReceipt {
+    readonly id: A2AMessageId;
+    readonly seq?: number;
+    /** `sent`, or `queued` when the relay was unreachable (outbox retry). */
+    readonly status: string;
+}
+export type BackendState = 'starting' | 'ready' | 'restarting' | 'stopped' | 'error';
+export interface BackendStatus {
+    readonly backend: BackendKind;
+    readonly state: BackendState;
+    readonly pid?: number;
+    readonly restarts: number;
+    readonly lastError?: string;
+    readonly relay?: string;
+    readonly home?: string;
+    readonly protocol?: string;
+    readonly version?: string;
+    /** The `soulnet` executable the backend spawned (soulnet backend only). */
+    readonly binary?: string;
+    /** How it was found: `setting` | `platform-package` | `path` | `plugin-bin`. */
+    readonly binarySource?: string;
+}
+export type NetworkEvent = {
+    readonly kind: 'message';
+    readonly message: InboundMessage;
+} | {
+    readonly kind: 'typing';
+    readonly fp: Fingerprint;
+    readonly on: boolean;
+} | {
+    readonly kind: 'friend_request';
+    readonly request: PendingRequest;
+} | {
+    readonly kind: 'friend_accept';
+    readonly friend: Friend;
+} | {
+    readonly kind: 'presence';
+    readonly fp: Fingerprint;
+    readonly online: boolean;
+} | {
+    readonly kind: 'status';
+    readonly status: BackendStatus;
+};
+/** Error raised by a backend call; `code` follows the soulnet JSON-RPC table (cmd/soulnet/README.md). */
+export declare class NetworkError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    readonly name = "NetworkError";
+    constructor(message: string, code: number, data?: unknown | undefined);
+}
+/** soulnet application error codes (branch on these, never on message text). */
+export declare const NetworkErrorCode: {
+    readonly noIdentity: -32001;
+    readonly notFriend: -32002;
+    readonly identityExists: -32003;
+    readonly notFound: -32004;
+    readonly badCard: -32005;
+    readonly network: -32006;
+    readonly badFile: -32007;
+    readonly noProfile: -32008;
+    /** Plugin-side: the backend process is not running / could not be reached. */
+    readonly peerUnavailable: -32099;
+};
+export interface NetworkClient {
+    readonly backend: BackendKind;
+    status(): BackendStatus;
+    /** `undefined` until an identity was created (first run). */
+    identity(): Promise<Identity | undefined>;
+    createIdentity(name: string): Promise<Identity>;
+    /** Own card URI (`soulmirror://card?...`). */
+    card(): Promise<string>;
+    parseCard(uri: string): Promise<{
+        fp: Fingerprint;
+        name: string;
+        uri: string;
+    }>;
+    readonly friends: {
+        list(): Promise<readonly Friend[]>;
+        pending(): Promise<readonly PendingRequest[]>;
+        /** Send a friend request from a card URI; `note` is both the local note and the greeting. */
+        add(cardUri: string, note?: string): Promise<Friend>;
+        accept(requestId: string, note?: string): Promise<Friend>;
+        reject(requestId: string): Promise<void>;
+        /** Change the local note and/or the per-friend protocol override (`protocol: ''` clears it). */
+        set(fp: Fingerprint, patch: {
+            remark?: string;
+            protocol?: string;
+        }): Promise<Friend>;
+        remove(fp: Fingerprint): Promise<void>;
+        /** A friend's card URI (from the card snapshot), e.g. to forward it. Not a friend → NetworkErrorCode.notFriend. */
+        card(fp: Fingerprint): Promise<{
+            fp: Fingerprint;
+            name: string;
+            uri: string;
+        }>;
+    };
+    send(to: Fingerprint, body: string, options?: SendOptions): Promise<SendReceipt>;
+    typing(to: Fingerprint, on: boolean): Promise<void>;
+    conversation(fp: Fingerprint, options?: {
+        since?: number;
+        limit?: number;
+    }): Promise<{
+        entries: readonly ConversationEntry[];
+        typing: boolean;
+    }>;
+    markRead(fp: Fingerprint, seq: number): Promise<void>;
+    presence(fps: readonly Fingerprint[]): Promise<Record<string, boolean>>;
+    subscribe(listener: (event: NetworkEvent) => void): () => void;
+    /** Stop the backend (clean `shutdown` for the peer process). Idempotent. */
+    dispose(): Promise<void>;
+    /** Test/dev seam: make the backend deliver an inbound message now. Absent on real backends. */
+    readonly debug?: {
+        inject(from: Fingerprint, body: string): void;
+    };
+}

package/lib/types/persona.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The alter's persona (P3, reshaped in P4 for ONE alter session): the
+ * system-prompt section the sessions plugin registers in the AGENT scope of
+ * the alter session (`agentCtx.systemPrompt.section(...)` inside the agent
+ * factory's `setup(agentCtx)`), shadowing the preset's `deployment:persona`,
+ * and the prompt VARIABLES it references.
+ *
+ * Why an agent-scoped section with variables, and not an edited preset file
+ * or an injected context message:
+ *   - the section is re-registered by `setup` on every create AND resume, so
+ *     it survives a dsh restart; the system prompt is assembled for every
+ *     step, so it survives compaction;
+ *   - `{{variable}}` groups resolve at render time against the registered
+ *     variable PROVIDERS, evaluated per assembly, so an edit of protocol.md,
+ *     of a friend's override / tier, or a new friend reaches the very next
+ *     turn without a restart (dsh-system-prompt renders strictly: every group
+ *     below must have a registered provider that returns a string — see
+ *     `PERSONA_VARIABLES`);
+ *   - the per-TURN friend context (`trigger_*`) is resolved from the session
+ *     log at assembly time: the friend whose mail woke this turn, or "none"
+ *     for an owner instruction (the owner may name any friend; the roster
+ *     carries every friend's fingerprint, tier and override).
+ */
+/** Section name of dsh-system-prompt's persona slot (`PERSONA_SECTION` in @deepseek-ai/dsh-system-prompt). */
+export declare const PERSONA_SECTION = "deployment:persona";
+/** Order of that slot (`PERSONA_ORDER`). */
+export declare const PERSONA_ORDER = 0;
+/** The variables the template references; each has an agent-scoped provider. */
+export declare const PERSONA_VARIABLES: {
+    readonly owner: "soulmirror_owner";
+    /** Roster of every friend: name, fingerprint, tier, protocol override. */
+    readonly friends: "soulmirror_friends";
+    /** The friend whose mail woke THIS turn (name), or "none" (owner instruction / unknown). */
+    readonly triggerFriend: "soulmirror_trigger_friend";
+    readonly triggerFriendFp: "soulmirror_trigger_friend_fp";
+    readonly triggerTier: "soulmirror_trigger_tier";
+    readonly triggerProtocol: "soulmirror_trigger_friend_protocol";
+    readonly protocol: "soulmirror_protocol";
+    /** Pending drafts awaiting the owner's review (count + one line each). */
+    readonly drafts: "soulmirror_pending_drafts";
+};
+/** Persona text of the alter session; `{{…}}` groups are the variables above. */
+export declare const PERSONA_TEMPLATE: string;
+/** Text shown when a variable has no content (the renderer refuses empty values). */
+export declare const PERSONA_NONE = "(none)";

package/lib/types/policy.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Reply policy of the alter (P3, reshaped in P4 for the single alter session)
+ * — pure, no I/O, unit-tested in test/policy.test.ts:
+ *
+ *   - `ReplyTier` per friend: `notify` (inbound mail is appended to the alter
+ *     session, no turn), `draft` (a turn is woken; the alter's reply is stored
+ *     as a PENDING DRAFT the owner reviews on the SoulMirror page), `auto` (a
+ *     turn is woken; the reply is sent without review, rate-limited per
+ *     friend per hour).
+ *   - `routeInbound()` — what to do with one inbound mail: append only, or
+ *     append AND wake the alter. The loop guard lives here: mail flagged
+ *     `auto` (another alter's automatic reply) never wakes a turn, and mail
+ *     from a non-friend never does either.
+ *   - `sendGate()` — whether `soulmirror_send_message` may send now or must
+ *     queue a draft. Owner-initiated turns send freely (SoulMirror rule:
+ *     friend messages on the owner's instruction are direct; only tasks /
+ *     money need confirmation). Inbound-triggered turns send freely only to
+ *     the friend who wrote, in the `auto` tier and under the hourly cap;
+ *     everything else becomes a draft for the owner. There is no dsh
+ *     approval panel in this path any more (P4).
+ *   - `HourlyWindow` — the per-friend sliding-window counter behind the cap.
+ */
+export type ReplyTier = 'notify' | 'draft' | 'auto';
+export declare const REPLY_TIERS: readonly ReplyTier[];
+export declare const DEFAULT_REPLY_TIER: ReplyTier;
+export declare const DEFAULT_AUTO_REPLY_PER_HOUR = 20;
+export declare function isReplyTier(value: unknown): value is ReplyTier;
+export declare function normalizeTier(value: unknown, fallback?: ReplyTier): ReplyTier;
+/**
+ * What woke the current turn of the alter session:
+ *   - `owner`: the owner typed an instruction (a `user/message` with
+ *     `source.kind === 'user'`) — from the SoulMirror page composer or dsh's
+ *     own input bar. `fp` is never set: an instruction that names a friend
+ *     is still the owner speaking (the persona resolves the friend as "none");
+ *   - `inbound`: mail from a friend woke the turn; `fp` / `name` identify
+ *     that friend (the per-friend tier and protocol override are resolved from
+ *     it, per turn);
+ *   - `inbound-auto`: that mail was itself flagged `auto` (should never wake a
+ *     turn — kept for the belt-and-braces branch in the gate);
+ *   - `unknown`: no user message in the current turn could be attributed (a
+ *     tool call from another session, a steer, a resumed turn …).
+ */
+export interface TurnTrigger {
+    readonly kind: 'owner' | 'inbound' | 'inbound-auto' | 'unknown';
+    /** Fingerprint of the friend whose mail woke the turn (inbound kinds only). */
+    readonly fp?: string;
+    /** Display name of that friend at delivery time. */
+    readonly name?: string;
+    /** A2A id of that mail. */
+    readonly messageId?: string;
+}
+export declare const UNKNOWN_TRIGGER: TurnTrigger;
+export interface InboundRoute {
+    /** Wake a model turn (the mail is delivered through the agent inbox) or append only. */
+    readonly action: 'wake' | 'append';
+    /** Why it was not woken (logged). */
+    readonly reason?: 'tier-notify' | 'loop-guard-auto' | 'not-a-friend';
+}
+export interface RouteInboundInput {
+    readonly tier: ReplyTier;
+    /** The mail carries the A2A `auto` flag (another alter's automatic reply). */
+    readonly auto: boolean;
+    /** The sender is in the friend list (the peer only archives friend mail, but the session layer may lag). */
+    readonly isFriend: boolean;
+}
+export declare function routeInbound(input: RouteInboundInput): InboundRoute;
+export type SendGateReason = 'owner-initiated' | 'auto-tier' | 'draft-tier' | 'notify-tier' | 'rate-limited' | 'loop-guard-auto' | 'unknown-trigger' | 'other-friend';
+export type SendDecision = 
+/** Send now; `auto` says whether to flag the wire message as an automatic reply. */
+{
+    readonly kind: 'allow';
+    readonly auto: boolean;
+    readonly reason: 'owner-initiated' | 'auto-tier';
+}
+/** Do not send: store a pending draft for the owner to review on the page. */
+ | {
+    readonly kind: 'draft';
+    readonly reason: Exclude<SendGateReason, 'owner-initiated' | 'auto-tier'>;
+};
+export interface SendGateInput {
+    readonly trigger: TurnTrigger;
+    /** The target friend of this send. */
+    readonly target: string;
+    /** Effective reply tier of the TARGET friend. */
+    readonly tier: ReplyTier;
+    /** Automatic replies already sent to the target in the current hour window. */
+    readonly autoSentInWindow: number;
+    /** `autoReplyPerHour` (<= 0 disables automatic sends entirely). */
+    readonly limit: number;
+}
+export declare function sendGate(input: SendGateInput): SendDecision;
+export declare const HOUR_MS = 3600000;
+/** Sliding one-hour window of timestamps per key (friend fingerprint). */
+export declare class HourlyWindow {
+    private readonly windowMs;
+    private readonly hits;
+    constructor(windowMs?: number);
+    /** Timestamps still inside the window for `key`, oldest first. */
+    count(key: string, now?: number): number;
+    /** Record one hit for `key`; returns the new count. */
+    record(key: string, now?: number): number;
+    /** Milliseconds until the oldest hit leaves the window (0 when none). */
+    retryAfter(key: string, now?: number): number;
+    private prune;
+}