@deepseek-ai/dsh-action-cards 0.0.0-stage → 0.2.2-alpha.2

package/lib/types/index.js

@@ -0,0 +1,398 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+/** Optional action cards below an answer: the `propose_action` tool, card state, user actions and status notices for registered kinds. */
+import { Service } from '@deepseek-ai/cordis';
+import { z } from 'zod';
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { createUserMessage, HarnessError } from '@deepseek-ai/dsh-llm';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { appendPluginRecord, SessionSeq } from '@deepseek-ai/dsh-session';
+import { actionCardProjection, PROPOSE_ACTION } from "./projection.js";
+/** Deployment-tunable limits for offering cards. */
+export const Config = z.object({
+    /** Queued next-turn user messages at or above which `propose_action` refuses, so no card is offered. */
+    queuedMessageLimit: z.number().int().min(1).default(2),
+}).prefault({});
+/** The user action every card offers; the shared service records it. */
+const DISMISS = 'dismiss';
+/** Phases the projection derives from the log; no decision may record them. */
+const DERIVED_PHASES = ['replaced'];
+/** Phases after which no user action changes the card. */
+const FINAL_PHASES = ['dismissed', ...DERIVED_PHASES];
+/** Tool whose successful loads activate `propose_action`; its `name` argument names the skill. */
+const SKILL_TOOL = 'skill';
+const skillArguments = z.object({ name: z.string() });
+const STATUS_PREAMBLE = 'Latest status of action cards from user actions and background work. '
+    + 'These are status facts, not a request to start or retry work. Use these receipts instead of the earlier proposal when describing progress.';
+const STATUS_CLOSING = 'Continue with the user’s current request.';
+/**
+ * Whether a plugin must refuse new work: its fiber or an ancestor is disposed or unloading, since a parent's disposal
+ * begins before the plugin's own effects run, or the plugin's own drain has begun.
+ * @param owner - the plugin's fiber.
+ * @param draining - whether the plugin's drain effect has started.
+ * @returns whether the plugin is stopping.
+ */
+export function isPluginStopping(owner, draining) {
+    for (let fiber = owner;; fiber = fiber.parent.fiber) {
+        if (fiber.uid === null || fiber.state === 5 /* FiberState.UNLOADING */)
+            return true;
+        if (fiber.parent.fiber === fiber)
+            return draining;
+    }
+}
+/** A refused `propose_action` call; the message tells the model what to do instead. */
+export class ActionCardError extends HarnessError {
+}
+/** Own entries only: browser-supplied ids such as `toString` never reach inherited object members. */
+function ownEntry(record, key) {
+    return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+function refused(reason) {
+    return { status: 'refused', reason };
+}
+function issuesOf(error) {
+    return 'Invalid details: ' + error.issues.map(issue => `${['details', ...issue.path.map(String)].join('.')}: ${issue.message}`).join('; ');
+}
+/** Card tool, kind registry, Session projection, user actions and status notices. */
+let ActionCards = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _act_decorators;
+    return class ActionCards extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _act_decorators = [Remote];
+            __esDecorate(this, null, _act_decorators, { kind: "method", name: "act", static: false, private: false, access: { has: obj => "act" in obj, get: obj => obj.act }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        config = __runInitializers(this, _instanceExtraInitializers);
+        static inject = ['tools', 'agents', 'sessionProjections', 'remoteAccess'];
+        static Config = Config;
+        projection;
+        kinds = new Map();
+        /**
+         * Actions whose kind unregistered. Cordis disposes a plugin's effects concurrently, so a kind's unload drain can
+         * still record the outcome of its in-flight work after its registration is gone.
+         */
+        retired = new Set();
+        /** Skills of registered kinds each live agent has loaded; `propose_action` is declared while one is still registered. */
+        loaded = new Map();
+        /** Kind skills each agent loaded in its latest turn. */
+        turnLoads = new Map();
+        /** The call accepted in each agent's latest turn, until its result fails. */
+        accepted = new Map();
+        actions = new Map();
+        closing = false;
+        owner;
+        /**
+         * @param ctx - Owning plugin context.
+         * @param config - Validated card limits; direct composition without a config gets the schema defaults.
+         */
+        constructor(ctx, config = Config.parse({})) {
+            super(ctx, 'actionCards');
+            this.config = config;
+            this.owner = ctx.fiber;
+        }
+        async [Service.init]() {
+            this.projection = await this.ctx.sessionProjections.register(actionCardProjection);
+            this.ctx.tools.register(defineTool({
+                name: PROPOSE_ACTION,
+                description: 'Show the user one optional action card under this answer. Call only as the skill that names the action instructs.',
+                parameters: {
+                    action: { type: 'string', required: true, description: 'Action name from the skill.' },
+                    title: { type: 'string', required: true, description: 'Card title.' },
+                    brief: { type: 'string', required: true, description: 'What the action does, in the user\'s language.' },
+                    details: { type: 'object', additionalProperties: true, required: true, description: 'Fields the skill lists for this action.' },
+                },
+                output: {
+                    schema: {
+                        type: 'object', additionalProperties: false,
+                        properties: {
+                            action: { type: 'string', required: true }, title: { type: 'string', required: true }, invitation: { type: 'string', required: true },
+                        },
+                    },
+                    render: (_args, value) => [{ type: 'text', text: `Card shown below your answer. Do not restate it. ${value.invitation}` }],
+                },
+                execute: (args, exec) => Promise.resolve(this.propose(args, exec)),
+            }), { when: ({ agent }) => this.declares(agent) });
+            this.ctx.on('tools/result', (exec, result) => {
+                const agent = exec.agent;
+                if (agent === undefined)
+                    return;
+                if (exec.name === PROPOSE_ACTION) {
+                    if (result.isError && this.accepted.get(agent)?.callId === exec.callId)
+                        this.accepted.delete(agent);
+                    return;
+                }
+                // Loads by subagents or from code activate nothing: `propose_action` refuses both callers.
+                if (exec.parent !== undefined || !this.ctx.agents.roots().includes(agent))
+                    return;
+                const skill = exec.name === SKILL_TOOL && !result.isError ? skillArguments.safeParse(exec.arguments) : undefined;
+                if (skill?.success !== true || ![...this.kinds.values()].some(kind => kind.skill === skill.data.name))
+                    return;
+                const turn = this.ctx.agents.turnBoundaryOf(agent.session).lastTurn;
+                const loads = this.turnLoads.get(agent);
+                if (loads?.turn === turn)
+                    loads.skills.add(skill.data.name);
+                else
+                    this.turnLoads.set(agent, { turn, skills: new Set([skill.data.name]) });
+                this.loaded.set(agent, new Set([...this.loaded.get(agent) ?? [], skill.data.name]));
+            });
+            this.ctx.on('agent/disposed', ({ agent }) => {
+                this.loaded.delete(agent);
+                this.turnLoads.delete(agent);
+                this.accepted.delete(agent);
+            });
+            this.ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+                const decision = await next();
+                if (decision.kind === 'reject' || signal.aborted || this.isStopping())
+                    return decision;
+                const state = this.projection.stateOf(agent.session);
+                const pending = Object.values(state.pendingStatus);
+                if (pending.length === 0)
+                    return decision;
+                const receipts = Object.values(state.view.decisions).filter(receipt => Object.hasOwn(state.pendingStatus, receipt.callId));
+                const guidance = new Set(receipts.flatMap(receipt => this.kinds.get(receipt.action)?.statusGuidance ?? []));
+                const updates = receipts.map((receipt) => {
+                    const fields = this.kinds.get(receipt.action)?.statusFields;
+                    const data = receipt.data === undefined || fields === undefined ? receipt.data
+                        : Object.fromEntries(Object.entries(receipt.data).filter(([key]) => fields.includes(key)));
+                    return { action: receipt.action, callId: receipt.callId, title: ownEntry(state.view.proposals, receipt.callId)?.title,
+                        phase: receipt.phase, ...data === undefined ? {} : { data } };
+                });
+                return { ...decision, messages: [...decision.messages, createUserMessage({
+                            source: { kind: 'action-cards', through: SessionSeq(Math.max(...pending)), form: 'notice', summary: 'Action card status updated' },
+                            content: [{ type: 'text', text: [STATUS_PREAMBLE, ...guidance, STATUS_CLOSING].join(' ') + '\n' + JSON.stringify(updates) }],
+                        })] };
+            }, { prepend: true });
+            this.ctx.effect(() => async () => {
+                this.closing = true;
+                await Promise.allSettled([...this.actions.values()]);
+            }, 'action-cards: drain user actions');
+        }
+        /**
+         * Register one action kind for the caller's lifetime.
+         * @param kind - the kind's skill, details schema, verbs and handler.
+         * @returns disposer removing the kind; actions on its cards are then unavailable.
+         * @throws when another kind already registered the same action.
+         */
+        register(kind) {
+            const typed = (proposal) => {
+                const details = kind.details.safeParse(proposal.details);
+                return details.success ? { ...proposal, details: details.data } : undefined;
+            };
+            const reconcile = kind.reconcile?.bind(kind);
+            const entry = {
+                skill: kind.skill, invitation: kind.invitation, verbs: kind.verbs, openPhases: kind.openPhases ?? [],
+                statusGuidance: kind.statusGuidance, statusFields: kind.statusFields,
+                detailsIssues: (details) => {
+                    const parsed = kind.details.safeParse(details);
+                    return parsed.success ? undefined : issuesOf(parsed.error);
+                },
+                dismissal: (proposal, payload) => {
+                    const card = typed(proposal);
+                    return card === undefined ? undefined : kind.dismissal?.(card, payload);
+                },
+                // A card whose details no longer validate never reached the kind, so the kind has nothing to reconcile.
+                reconcile: reconcile === undefined ? undefined : async (agent, proposal) => {
+                    const card = typed(proposal);
+                    if (card !== undefined)
+                        await reconcile(agent, card);
+                },
+                act: (agent, proposal, verb, payload) => {
+                    const card = typed(proposal);
+                    return card === undefined ? Promise.resolve(refused('unavailable')) : kind.act(agent, card, verb, payload);
+                },
+            };
+            const dispose = this.ctx.effect(() => {
+                if (this.kinds.has(kind.action))
+                    throw new Error(`action-cards: action "${kind.action}" is already registered`);
+                this.kinds.set(kind.action, entry);
+                return () => {
+                    this.kinds.delete(kind.action);
+                    this.retired.add(kind.action);
+                };
+            }, `action-cards: kind ${kind.action}`);
+            return () => { void dispose(); };
+        }
+        /**
+         * Record a card decision in the Session log; the next model request reports it.
+         * @param agent - agent whose Session owns the card.
+         * @param decision - the card's new state.
+         * @throws when no kind ever registered the decision's action with this service, or its phase is one the projection derives.
+         */
+        record(agent, decision) {
+            if (!this.kinds.has(decision.action) && !this.retired.has(decision.action)) {
+                throw new Error(`action-cards: cannot record a decision for unregistered action "${decision.action}"`);
+            }
+            if (DERIVED_PHASES.includes(decision.phase))
+                throw new Error(`action-cards: phase "${decision.phase}" is derived from the log and cannot be recorded`);
+            this.append(agent, decision);
+        }
+        /**
+         * Read the cards of one Session.
+         * @param session - a Session whose projections are prepared.
+         * @returns proposals and decisions by call id.
+         */
+        view(session) {
+            return this.projection.stateOf(session).view;
+        }
+        /**
+         * Apply a user action to a logged card. Shared checks run first, then the kind reconciles the card; `dismiss` is
+         * recorded here and every other verb goes to the card's kind. `dismiss` also works on an unstarted card whose kind
+         * is no longer registered. Concurrent actions on one card share one operation.
+         * @param agent - live root resolved from the displayed Session.
+         * @param callId - the card's `propose_action` call id.
+         * @param verb - `dismiss` or one of the kind's verbs.
+         * @param payload - kind-defined fields such as a chosen location.
+         * @returns acceptance of background work, the decision in effect, or a refusal.
+         */
+        act(agent, callId, verb, payload) {
+            if (this.isStopping())
+                return Promise.resolve(refused('closing'));
+            if (!this.ctx.agents.roots().includes(agent))
+                return Promise.resolve(refused('not-live-root'));
+            const proposal = ownEntry(this.projection.stateOf(agent.session).view.proposals, callId);
+            if (proposal === undefined)
+                return Promise.resolve(refused('unknown'));
+            const kind = this.kinds.get(proposal.action);
+            if (verb === DISMISS)
+                return this.coalesce(agent, callId, () => this.dismiss(agent, kind, proposal, payload));
+            const policy = kind === undefined ? undefined : ownEntry(kind.verbs, verb);
+            if (kind === undefined || policy === undefined)
+                return Promise.resolve(refused('unavailable'));
+            if (policy.global === true && !this.ctx.remoteAccess.allows({ kind: 'global' }))
+                return Promise.resolve(refused('access-denied'));
+            return this.coalesce(agent, callId, () => this.perform(agent, kind, proposal, verb, policy, payload));
+        }
+        /** Share one operation per card, run under the Agent's initiator, until it settles. */
+        coalesce(agent, callId, run) {
+            const key = JSON.stringify([agent.id, callId]);
+            const existing = this.actions.get(key);
+            if (existing !== undefined)
+                return existing;
+            const operation = this.ctx.agents.withInitiator(agent, run).finally(() => { this.actions.delete(key); });
+            this.actions.set(key, operation);
+            return operation;
+        }
+        /**
+         * Await the kind's reconciliation. A kind that unloads meanwhile still handles the action and refuses it itself.
+         * @returns a refusal when reconciliation failed or the root closed meanwhile; undefined to continue.
+         */
+        async reconciled(agent, kind, proposal, verb) {
+            if (kind.reconcile === undefined)
+                return undefined;
+            try {
+                await kind.reconcile(agent, proposal);
+            }
+            catch (error) {
+                this.ctx.logger.warn('Cannot reconcile action card %s before %s: %s', proposal.callId, verb, String(error));
+                return refused('unavailable');
+            }
+            return this.ctx.agents.roots().includes(agent) ? undefined : refused('not-live-root');
+        }
+        async dismiss(agent, kind, proposal, payload) {
+            const refusal = kind === undefined ? undefined : await this.reconciled(agent, kind, proposal, DISMISS);
+            if (refusal !== undefined)
+                return refusal;
+            const decision = ownEntry(this.projection.stateOf(agent.session).view.decisions, proposal.callId);
+            // Without its kind no recorded phase is known to be open, and the kind may return to act on it.
+            if (decision !== undefined && (FINAL_PHASES.includes(decision.phase) || kind?.openPhases.includes(decision.phase) !== true)) {
+                return { status: 'settled', decision };
+            }
+            const data = kind?.dismissal(proposal, payload);
+            const dismissed = { callId: proposal.callId, action: proposal.action, phase: 'dismissed', ...data === undefined ? {} : { data } };
+            this.append(agent, dismissed);
+            return { status: 'settled', decision: dismissed };
+        }
+        async perform(agent, kind, proposal, verb, policy, payload) {
+            const refusal = await this.reconciled(agent, kind, proposal, verb);
+            if (refusal !== undefined)
+                return refusal;
+            const decision = ownEntry(this.projection.stateOf(agent.session).view.decisions, proposal.callId);
+            if (decision !== undefined && FINAL_PHASES.includes(decision.phase))
+                return { status: 'settled', decision };
+            if (policy.writes === true && this.ctx.get('sandboxPolicy')?.resolve({ session: agent.session }).mode === 'read-only')
+                return refused('read-only');
+            return await kind.act(agent, proposal, verb, payload);
+        }
+        append(agent, decision) {
+            appendPluginRecord(agent.session, 'plugin:action-cards/decision', decision);
+        }
+        /** Whether `propose_action` is declared for this agent's next step. */
+        declares(agent) {
+            const skills = this.loaded.get(agent);
+            return skills !== undefined && [...this.kinds.values()].some(kind => skills.has(kind.skill));
+        }
+        propose(args, exec) {
+            const agent = exec.agent;
+            // Step admission declares the tool only to an agent; calls dispatched from code are not logged as tool calls,
+            // so no card could follow them.
+            if (agent === undefined || exec.parent !== undefined)
+                throw new ActionCardError('Call propose_action directly, not from code.', 'ACTION_CARD_NESTED');
+            // Only a live root can act on a card, so a subagent's card could never be used.
+            if (!this.ctx.agents.roots().includes(agent))
+                throw new ActionCardError('Cards are offered in the main conversation only.', 'ACTION_CARD_ROOT');
+            if (this.projection.stateOf(agent.session).queued >= this.config.queuedMessageLimit) {
+                throw new ActionCardError('The user has queued more messages; show no card and answer briefly.', 'ACTION_CARD_QUEUED');
+            }
+            const kind = this.kinds.get(args.action);
+            // Admission is decided when the step starts, so the last kind can unregister before this call runs.
+            if (kind === undefined)
+                throw new ActionCardError(`Unknown action "${args.action}". Registered actions: ${[...this.kinds.keys()].join(', ') || 'none'}.`, 'ACTION_CARD_UNKNOWN');
+            const turn = this.ctx.agents.turnBoundaryOf(agent.session).lastTurn;
+            const loads = this.turnLoads.get(agent);
+            if (loads?.turn !== turn || !loads.skills.has(kind.skill)) {
+                throw new ActionCardError(`Load skill ${kind.skill} first, then call propose_action.`, 'ACTION_CARD_SKILL');
+            }
+            if (args.title.trim() === '' || args.brief.trim() === '')
+                throw new ActionCardError('Write a title and a brief.', 'ACTION_CARD_BLANK');
+            const issues = kind.detailsIssues(args.details);
+            if (issues !== undefined)
+                throw new ActionCardError(issues, 'ACTION_CARD_DETAILS');
+            if (this.accepted.get(agent)?.turn === turn || Object.values(this.view(agent.session).proposals).some(card => card.turn === turn)) {
+                throw new ActionCardError('One card per turn; the earlier card stands.', 'ACTION_CARD_LIMIT');
+            }
+            this.accepted.set(agent, { turn, callId: exec.callId });
+            return { action: args.action, title: args.title.trim(), invitation: kind.invitation };
+        }
+        isStopping() {
+            return isPluginStopping(this.owner, this.closing);
+        }
+    };
+})();
+export { ActionCards };
+export default ActionCards;
+//# sourceMappingURL=index.js.map

package/lib/types/projection.d.ts

@@ -0,0 +1,66 @@
+/** Recover card proposals from logged `propose_action` calls and decisions from plugin records. */
+import { z } from 'zod';
+import { ToolCallId } from '@deepseek-ai/dsh-llm';
+import { SessionLogOffset } from '@deepseek-ai/dsh-session';
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+/** Model-facing name of the card tool. */
+export declare const PROPOSE_ACTION = "propose_action";
+/** Kind-defined JSON object of a proposal or decision. */
+export declare const fieldsSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+/** Arguments of a `propose_action` call; blank titles and briefs create no card. */
+export declare const argumentsSchema: z.ZodObject<{
+    action: z.ZodString;
+    title: z.ZodString;
+    brief: z.ZodString;
+    details: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+}, z.core.$strip>;
+/** Recorded decision of one card. */
+export declare const decisionSchema: z.ZodObject<{
+    callId: z.ZodPipe<z.ZodString, z.ZodTransform<ToolCallId, string>>;
+    action: z.ZodString;
+    phase: z.ZodString;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+declare const stateSchema: z.ZodObject<{
+    inheritedEventCount: z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionLogOffset, number>>;
+    view: z.ZodObject<{
+        proposals: z.ZodRecord<z.ZodString, z.ZodObject<{
+            callId: z.ZodPipe<z.ZodString, z.ZodTransform<ToolCallId, string>>;
+            turn: z.ZodNumber;
+            action: z.ZodString;
+            title: z.ZodString;
+            brief: z.ZodString;
+            details: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        }, z.core.$strict>>;
+        decisions: z.ZodRecord<z.ZodString, z.ZodObject<{
+            callId: z.ZodPipe<z.ZodString, z.ZodTransform<ToolCallId, string>>;
+            action: z.ZodString;
+            phase: z.ZodString;
+            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        }, z.core.$strict>>;
+    }, z.core.$strip>;
+    calls: z.ZodRecord<z.ZodString, z.ZodObject<{
+        details: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        action: z.ZodString;
+        title: z.ZodString;
+        brief: z.ZodString;
+        turn: z.ZodNumber;
+    }, z.core.$strict>>;
+    admittedTurn: z.ZodNullable<z.ZodNumber>;
+    pendingStatus: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    queued: z.ZodNumber;
+}, z.core.$strip>;
+/** Fold state; `view` is also the Client wire value. */
+export type ActionCardState = z.infer<typeof stateSchema>;
+/** Type of {@link actionCardProjection}: the fold plus its Client view wire. */
+export type ActionCardProjectionDefinition = Omit<ProjectionDefinition<'actionCards', ActionCardState>, 'wire'> & {
+    readonly wire: NonNullable<ProjectionDefinition<'actionCards', ActionCardState>['wire']>;
+};
+/**
+ * Full-Session fold. A successful `propose_action` result admits the call as a card, at most one per turn;
+ * the first admitted call of a turn wins. A newer card of any kind replaces every unstarted earlier card.
+ * Events inherited by a forked Session create no proposals or decisions.
+ */
+export declare const actionCardProjection: ActionCardProjectionDefinition;
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,122 @@
+/** Recover card proposals from logged `propose_action` calls and decisions from plugin records. */
+import { z } from 'zod';
+import { ToolCallId } from '@deepseek-ai/dsh-llm';
+import { pluginRecordOf, SessionLogOffset } from '@deepseek-ai/dsh-session';
+/** Model-facing name of the card tool. */
+export const PROPOSE_ACTION = 'propose_action';
+/** Kind-defined JSON object of a proposal or decision. */
+export const fieldsSchema = z.record(z.string(), z.json());
+/** Arguments of a `propose_action` call; blank titles and briefs create no card. */
+export const argumentsSchema = z.object({
+    action: z.string().min(1),
+    title: z.string().trim().min(1),
+    brief: z.string().trim().min(1),
+    details: fieldsSchema,
+});
+const proposalSchema = z.object({
+    callId: z.string().min(1).transform(ToolCallId),
+    turn: z.number().int().nonnegative(),
+    action: z.string().min(1),
+    title: z.string().min(1),
+    brief: z.string().min(1),
+    details: fieldsSchema,
+}).strict();
+/** Recorded decision of one card. */
+export const decisionSchema = z.object({
+    callId: z.string().min(1).transform(ToolCallId),
+    action: z.string().min(1),
+    phase: z.string().min(1),
+    data: fieldsSchema.optional(),
+}).strict();
+const viewSchema = z.object({
+    proposals: z.record(z.string(), proposalSchema),
+    decisions: z.record(z.string(), decisionSchema),
+});
+const stateSchema = z.object({
+    /** Fork-inherited prefix length; inherited events create no proposals or decisions. */
+    inheritedEventCount: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionLogOffset),
+    view: viewSchema,
+    /** `propose_action` calls of the open turn still waiting for their result. */
+    calls: z.record(z.string(), proposalSchema.omit({ callId: true })),
+    /** Turn of the latest admitted proposal; later calls of that turn create no card. */
+    admittedTurn: z.number().int().nullable(),
+    /** Decisions not yet reported to the model, by call id, with the seq of their record. */
+    pendingStatus: z.record(z.string(), z.number()),
+    /** User messages still queued for later turns, folded from inbox splices; the card tool compares it with its limit. */
+    queued: z.number().int().nonnegative(),
+});
+/**
+ * Full-Session fold. A successful `propose_action` result admits the call as a card, at most one per turn;
+ * the first admitted call of a turn wins. A newer card of any kind replaces every unstarted earlier card.
+ * Events inherited by a forked Session create no proposals or decisions.
+ */
+export const actionCardProjection = {
+    key: 'actionCards', stateVersion: 2, stateSchema,
+    init: (_header, inheritedEventCount) => ({
+        inheritedEventCount, view: { proposals: {}, decisions: {} }, calls: {}, admittedTurn: null, pendingStatus: {}, queued: 0,
+    }),
+    apply: (state, event) => {
+        if (event.seq < state.inheritedEventCount)
+            return state;
+        switch (event.type) {
+            case 'turn/start':
+                // A turn's calls settle inside it; a call left without a result never becomes a card.
+                return Object.keys(state.calls).length === 0 ? state : { ...state, calls: {} };
+            case 'agent/inbox/spliced':
+                if (event.data.target !== 'next-turn')
+                    return state;
+                return { ...state, queued: Math.max(0, state.queued - (event.data.removedCount ?? 0) + event.data.inserted.length) };
+            case 'user/message': {
+                if (event.data.source.kind !== 'action-cards')
+                    return state;
+                const through = event.data.source.through;
+                return { ...state, pendingStatus: Object.fromEntries(Object.entries(state.pendingStatus).filter(([, seq]) => seq > through)) };
+            }
+            case 'tool/call': {
+                if (event.data.name !== PROPOSE_ACTION)
+                    return state;
+                let raw;
+                try {
+                    raw = JSON.parse(event.data.arguments);
+                }
+                catch {
+                    return state;
+                } // Malformed model JSON failed in the tool too and creates no card.
+                const parsed = argumentsSchema.safeParse(raw);
+                if (!parsed.success)
+                    return state;
+                return { ...state, calls: { ...state.calls, [event.data.callId]: { turn: event.data.turn, ...parsed.data } } };
+            }
+            case 'tool/result': {
+                const callId = event.data.message.toolCallId;
+                const call = Object.hasOwn(state.calls, callId) ? state.calls[callId] : undefined;
+                if (call === undefined)
+                    return state;
+                const calls = Object.fromEntries(Object.entries(state.calls).filter(([id]) => id !== callId));
+                if (event.data.message.isError === true || state.admittedTurn === call.turn)
+                    return { ...state, calls };
+                const decisions = { ...state.view.decisions };
+                // A newer card supersedes every unstarted card; the model made that choice, so no status is reported.
+                for (const earlier of Object.values(state.view.proposals)) {
+                    if (decisions[earlier.callId] === undefined)
+                        decisions[earlier.callId] = { callId: earlier.callId, action: earlier.action, phase: 'replaced' };
+                }
+                return { ...state, calls, admittedTurn: call.turn,
+                    view: { proposals: { ...state.view.proposals, [callId]: { callId, ...call } }, decisions } };
+            }
+            default: {
+                const record = pluginRecordOf(event);
+                if (record?.type !== 'plugin:action-cards/decision')
+                    return state;
+                // A malformed or newer record is skipped; throwing here would fail every later read of this Session.
+                const decision = decisionSchema.safeParse(record.data);
+                if (!decision.success)
+                    return state;
+                return { ...state, view: { ...state.view, decisions: { ...state.view.decisions, [decision.data.callId]: decision.data } },
+                    pendingStatus: { ...state.pendingStatus, [decision.data.callId]: event.seq } };
+            }
+        }
+    },
+    wire: { summary: false, viewSchema, view: (state) => state.view },
+};
+//# sourceMappingURL=projection.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,81 @@
+/** Card proposals, recorded decisions and user-action results shared by every action kind. */
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+import type { ToolCallId } from '@deepseek-ai/dsh-llm/brand';
+import type { SessionSeq } from '@deepseek-ai/dsh-session/types';
+import type { JsonValue } from '@deepseek-ai/dsh-util-values';
+/** Kind-defined JSON fields of a proposal or decision; each kind validates its own fields. */
+export type ActionCardFields = Readonly<Record<string, JsonValue>>;
+/** One card admitted from a successful `propose_action` call. */
+export interface ActionCardProposal {
+    /** Id of the logged tool call. */
+    readonly callId: ToolCallId;
+    /** Turn whose answer the card follows. */
+    readonly turn: number;
+    /** Registered action kind named by the call. */
+    readonly action: string;
+    readonly title: string;
+    /** What the action does, in the user's language. */
+    readonly brief: string;
+    /** Fields the kind's skill asks for. */
+    readonly details: ActionCardFields;
+}
+/**
+ * Latest state of one card. Kinds define their own phases; `dismissed` is shared.
+ * `replaced` (a later proposal superseded an unstarted card) is derived from the
+ * log and never recorded.
+ */
+export interface ActionCardDecision {
+    readonly callId: ToolCallId;
+    readonly action: string;
+    readonly phase: string;
+    /** Kind-defined fields such as a chosen location or a created package. */
+    readonly data?: ActionCardFields | undefined;
+}
+/** Open-Session proposals and decisions by call id, excluded from Session summaries. */
+export interface ActionCardView {
+    readonly proposals: Readonly<Record<string, ActionCardProposal>>;
+    readonly decisions: Readonly<Record<string, ActionCardDecision>>;
+}
+/**
+ * Result of a user action. `accepted` starts background work that records its
+ * own progress; `settled` returns the decision now in effect; `refused` changed
+ * nothing; `unconfirmed` lost its outcome to an unloading owner, which the
+ * kind reconciles when the Session reopens.
+ */
+export type ActionCardResult = {
+    readonly status: 'accepted';
+} | {
+    readonly status: 'settled';
+    readonly decision: ActionCardDecision;
+} | {
+    readonly status: 'refused';
+    readonly reason: string;
+} | {
+    readonly status: 'unconfirmed';
+    readonly reason: string;
+};
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** Card status notice; other readers preserve the recorded text without this plugin.
+         * The producer uses through only to acknowledge delivered decisions.
+         * @persistenceAttribution
+         */
+        'action-cards': {
+            kind: 'action-cards';
+            through: SessionSeq;
+        } & ContextFormed;
+    }
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface PluginRecordMap {
+        /** Dismissals and kind-defined progress of action cards. */
+        'plugin:action-cards/decision': ActionCardDecision;
+    }
+}
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Action card proposals and decisions for the currently open Session. */
+        actionCards: SessionProjectionSummaryExcluded<ActionCardView>;
+    }
+}
+//# sourceMappingURL=types.d.ts.map