dsh-agent-persona 0.1.0

package/lib/endpoints.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The remote surface, in one place. The host registers exactly these names, the generator turns them
+ * into the ./remote and ./typert artifacts, and the browser half mounts what the generator produced —
+ * so the three never drift. Regenerate with `npm run generate:remote`.
+ */
+export declare const RPC_PACKAGE = "dsh-agent-persona";
+/**
+ * The cordis service name the host registers (super(ctx, 'agentPersona')) and the namespace the
+ * browser half reads (ctx.get('remote.agentPersona')). It is NOT the package name: filling these two
+ * fields with the package name mounts the namespace under a key nothing ever looks up.
+ */
+export declare const RPC_SERVICE = "agentPersona";
+export declare const RPC_CHANNEL = "/agent-persona";
+export declare const RPC_ENDPOINTS: readonly ['listPersonas', 'savePersona', 'deletePersona', 'movePersona', 'duplicatePersona', 'reorderPersona', 'listTargets', 'sessionHistory', 'sessionPrompt', 'tunePersona', 'listModels', 'savePrefs'];
+/** The three reads that take no argument. Everything else receives one JSON object. */
+export declare const RPC_NO_INPUT: readonly ['listPersonas', 'listTargets', 'listModels'];

package/lib/endpoints.js

@@ -0,0 +1,29 @@
+/**
+ * The remote surface, in one place. The host registers exactly these names, the generator turns them
+ * into the ./remote and ./typert artifacts, and the browser half mounts what the generator produced —
+ * so the three never drift. Regenerate with `npm run generate:remote`.
+ */
+export const RPC_PACKAGE = 'dsh-agent-persona';
+/**
+ * The cordis service name the host registers (super(ctx, 'agentPersona')) and the namespace the
+ * browser half reads (ctx.get('remote.agentPersona')). It is NOT the package name: filling these two
+ * fields with the package name mounts the namespace under a key nothing ever looks up.
+ */
+export const RPC_SERVICE = 'agentPersona';
+export const RPC_CHANNEL = '/agent-persona';
+export const RPC_ENDPOINTS = [
+    'listPersonas',
+    'savePersona',
+    'deletePersona',
+    'movePersona',
+    'duplicatePersona',
+    'reorderPersona',
+    'listTargets',
+    'sessionHistory',
+    'sessionPrompt',
+    'tunePersona',
+    'listModels',
+    'savePrefs',
+];
+/** The three reads that take no argument. Everything else receives one JSON object. */
+export const RPC_NO_INPUT = ['listPersonas', 'listTargets', 'listModels'];

package/lib/index.d.ts

@@ -0,0 +1,261 @@
+/**
+ * agent-persona — host half (v2: many personas, each with its own scope).
+ *
+ * Model
+ * -----
+ * A persona is a first-class record: `{ id, name, enabled, text, targets[] }`.
+ * Every target says WHERE the persona applies:
+ *
+ *     { kind: 'workspace' | 'sessionId', match: 'exact' | 'prefix' | 'regex' | 'contains', value: string }
+ *
+ * Resolution (see {@link resolvePersona}) is deliberately simple and explainable:
+ *
+ *   1. personas are tried in ARRAY ORDER (the settings page shows that order and
+ *      lets it be reordered) — the first match wins;
+ *   2. inside one persona the targets are OR-ed (any target matching is enough);
+ *   3. a persona with NO targets applies nowhere (a draft), it is never a catch-all: so it
+ *      belongs at the bottom of the list;
+ *   4. a DISABLED persona is skipped entirely;
+ *   5. a matching persona whose text is EMPTY wins and contributes nothing —
+ *      that is how you carve an exception out of a catch-all ("no persona here");
+ *   6. when nothing matches, the section renders `''` and `renderPrompt()` drops
+ *      it, so the agent keeps the stock DSH system prompt.
+ *
+ * Placement: ONE global system-prompt section at
+ * `getSectionOrder('DEPLOYMENT_PERSONA_PREFIX') + 1` (order 1) — right after the
+ * harness identity (-1000) and the persona prefix (0), ahead of every
+ * tool-guidance section (500+). Workspace `AGENTS.md` is not a section at all
+ * (`dsh-agent-instructions` turns it into a durable USER-role message whose own
+ * intro says it does not override system instructions), so a persona here
+ * outranks `AGENTS.md` structurally.
+ *
+ * Storage lives in this plugin's own directory — `$DSH_HOME/dsh-agent-persona/`
+ * holds `personas.json` (the data) and `state.json` (a load heartbeat), so a
+ * deployment does not scatter loose files across `$DSH_HOME`. The data file is
+ * re-read on every assembly when its `mtimeNs:size` stamp changes, so edits apply
+ * to the next request.
+ *
+ * The settings page offers dropdowns instead of asking for raw paths and ids;
+ * `listTargets` is what feeds them (workspaces + sessions with titles).
+ *
+ * Row config (all optional):
+ *   tuneProvider / tuneModel — pin the model used by the AI-tuning button for
+ *   this deployment; when unset it uses the model DSH itself is set to use
+ *   (`agentDefaultModel`), which is also what the settings page preselects.
+ *   storePath — override the persona store location (default
+ *   `$DSH_HOME/dsh-agent-persona/personas.json`).
+ */
+import Schema from '@deepseek-ai/schemastery';
+export declare const name = "agent-persona";
+/**
+ * Configuration. Written as a Schemastery schema so the defaults live here, the shape is checked
+ * when the row loads, and a wrong value fails loudly instead of being ignored.
+ */
+export declare const Config: Schema<Schemastery.ObjectS<{
+    /** Where the personas live. Empty means `$DSH_HOME/dsh-agent-persona/personas.json`. */
+    storePath: Schema<string, string>;
+}>, Schemastery.ObjectT<{
+    /** Where the personas live. Empty means `$DSH_HOME/dsh-agent-persona/personas.json`. */
+    storePath: Schema<string, string>;
+}>>;
+export declare const inject: string[];
+/** Persona injection modes: append after the preset persona, or replace it. */
+export declare const PERSONA_MODES: string[];
+/** Target vocabulary, surfaced to the settings page. */
+export declare const TARGET_KINDS: string[];
+export declare const TARGET_MATCHES: string[];
+/**
+ * Move one persona to an absolute position (what a drag-and-drop emits).
+ * @param store - the store to adjust in place.
+ * @param id - persona to move.
+ * @param toIndex - target position, clamped into range.
+ * @returns whether the order actually changed.
+ */
+export declare const reorderPersonas: (store: any, id: any, toIndex: any) => boolean;
+/**
+ * A workspace or a session belongs to exactly one persona. When a save claims a
+ * value that another persona holds with the same kind and the same exact value,
+ * the claim moves to the incoming persona and the other one loses that row.
+ *
+ * Only exact values can be reasoned about: prefix / regex / contains rows may
+ * still overlap, and the first match in list order wins there.
+ * @param store - the store to adjust in place.
+ * @param persona - the persona whose claims win.
+ * @returns the names of the personas that lost a row.
+ */
+export declare const takeOverClaims: (store: any, persona: any) => any[];
+export declare const normalizePrefs: (raw: any) => {
+    autosave: boolean;
+    showTab: boolean;
+    showSidebar: boolean;
+};
+export declare const sanitizePersona: (text: any, warn?: () => void) => string;
+/**
+ * Does one target claim this subject?
+ * @param target - normalized target record.
+ * @param subject - `{ cwd?: string, sessionId?: string }`.
+ * @returns true when the target matches; an unusable target (empty value, bad
+ * regex, or a subject field the session does not have) never matches.
+ */
+export declare const matchTarget: (target: any, subject: any) => any;
+/** The target list that claims this subject, empty when none does. */
+/**
+ * How specific one matching rule is. A session-level rule beats a directory-level
+ * one, and an exact value beats a pattern, so the most specific claim wins without
+ * the user having to order the list by hand.
+ * @param target - the matching row.
+ * @returns 6 (sessionId/exact) down to 1 (workspace pattern); a target-less
+ * persona scores 0, i.e. it only takes what nothing else claimed.
+ */
+export declare const targetSpecificity: (target: any) => number;
+export declare const matchingTargets: (persona: any, subject: any) => any;
+/**
+ * Pick the persona that owns this assembly.
+ * @param personas - the store's persona list, already in priority order.
+ * @param subject - `{ cwd?, sessionId? }` for the assembling agent.
+ * @returns the winning persona and why, or `reason: 'none'`.
+ */
+export declare const resolvePersona: (personas: any, subject: any) => any;
+export declare const subjectOf: (agent: any) => {
+    cwd: any;
+    sessionId: string;
+};
+/** The persona text one assembly should carry, or `''` for the stock prompt. */
+export declare const personaTextFor: (personas: any, agent: any, warn?: () => void) => string;
+/**
+ * Everything the picker needs about a session, out of ONE read of DSH's
+ * projection cache: the title, the first prompt and the latest prompt.
+ *
+ * The projection file is the cheapest source by a wide margin — a session log is
+ * 2.6x-5.8x larger on a real machine and is a zstd-compressed append-only file
+ * that cannot be seeked, so reading its tail would be the most expensive option
+ * of all. The service is tried first (the intended fast path) but its
+ * `recordFor(id)` needs an identity witness a listed header cannot reconstruct,
+ * so the file below is what actually answers; both are cached per process.
+ */
+/**
+ * Clip one message for transport without breaking its Markdown. A cut that lands
+ * inside an open ``` fence would swallow every line after it (and can push the
+ * renderer into its plain-text fallback), so the fence is closed first.
+ * @param text - the message body.
+ * @param maxChars - how much to keep.
+ * @returns the clipped body with a truncation note.
+ */
+export declare const clipMarkdown: (text: any, maxChars: any) => any;
+/**
+ * The candidate lists the settings page offers as dropdowns. Every source is
+ * probed defensively: a deployment whose services differ simply gets an empty
+ * list, and the page falls back to typing a value.
+ * @param ctx - host context.
+ * @param warn - warning sink.
+ * @returns workspaces (`{path,title,sessionCount}`) and the newest 200 sessions
+ * (`{id,title?,cwd,createdAt}`, newest first).
+ */
+export declare const collectTargets: (ctx: any, { personas, warn }?: {
+    personas?: any[];
+    warn?: () => void;
+}) => Promise<{
+    workspaces: any[];
+    sessions: any[];
+    hidden: {
+        subagents: number;
+        archived: number;
+        blank: number;
+    };
+}>;
+/**
+ * Apply a persona's injection mode to an assembled prompt.
+ *
+ * The persona text itself always rides in this plugin's own section, so
+ * `replace` only has to drop the deployment's persona line — `append` leaves the
+ * assembly untouched. A section already carrying something else (an agent preset
+ * or a subagent shadowed it) is never overwritten: another author's persona wins.
+ * @param assembly - the `system-prompt/assemble` value.
+ * @param options.mode - `append` or `replace`.
+ * @param options.deploymentPrefix - the deployment's own persona text, when readable.
+ * @returns the assembly to hand on (the input object when nothing changes).
+ */
+export declare const applyPersonaMode: (assembly: any, { mode, deploymentPrefix }: {
+    deploymentPrefix: any;
+    mode: any;
+}) => any;
+/**
+ * Session ids the user has archived. The registry is asked first; the workspace
+ * store file is the fallback, and an unreadable store simply means "none".
+ */
+export declare const collectArchivedSessionIds: (ctx: any) => Set<unknown>;
+/**
+ * The last system prompt a session actually sent: read out of its own event log, so it
+ * is the assembled text rather than a reconstruction of it.
+ * @param ctx - the plugin context.
+ * @param id - the session id.
+ * @returns the prompt text, or null when the log cannot be read.
+ */
+export declare const collectLastSystemPrompt: (ctx: any, id: any) => Promise<any>;
+/**
+ * What the persona view shows for one session: which persona applies, and the system
+ * prompt that session last sent.
+ * @param ctx - the plugin context.
+ * @param id - the session id.
+ * @param personas - the stored personas.
+ * @returns the view payload.
+ */
+export declare const sessionPromptFrom: (ctx: any, id: any, personas: any) => Promise<{
+    cwd?: undefined;
+    id: string;
+    available: boolean;
+    persona: any;
+    prompt: any;
+    reason: string;
+    matchedBy: any[];
+} | {
+    id: string;
+    available: boolean;
+    cwd: any;
+    reason: any;
+    matchedBy: any;
+    persona: {
+        id: any;
+        name: any;
+        mode: any;
+        fallback: boolean;
+        enabled: boolean;
+        text: any;
+        targets: any;
+    };
+    prompt: any;
+}>;
+/**
+ * The options a history call carries, in one place: the runtime used to forward a
+ * hand-written subset, so a new option (tail/keep) silently never reached the
+ * reader and 跳到最新 quietly read the beginning instead.
+ * @param input - the remote call's payload.
+ * @returns the reader options.
+ */
+export declare const historyOptions: (input: any) => {
+    offset: any;
+    events: any;
+    maxChars: any;
+    tail: boolean;
+    keep: any;
+};
+/**
+ * Read one window of a session's conversation.
+ *
+ * Storage is addressed through per-session handles and the backend is a
+ * zstd-compressed append-only log, so a read decompresses from the start: asking
+ * for many small pages costs far more than a few large ones. The contract is
+ * therefore one generous window plus `nextOffset`, and the page only fetches
+ * another window when the user asks for more. Each message is capped so a single
+ * huge tool output cannot blow up the payload or the DOM.
+ * @param ctx - host context.
+ * @param id - session id.
+ * @param options.offset - first event index to read (default 0).
+ * @param options.events - how many events to read in this window (default 2000, max 4000).
+ * @param options.maxChars - per-message text cap (default 1000).
+ * @returns a page: `{ messages, offset, nextOffset, done, eventCount, unavailable }`.
+ */
+export declare const collectSessionHistory: (ctx: any, id: any, options?: {}) => Promise<any>;
+/** The Connection RPC channel the browser half calls into (see the plugin standard). */
+/** Mount the prompt section, the store-backed service, and the load heartbeat. */
+export declare function apply(ctx: any, config?: {}): void;