dsh-loop-engine-allinone 0.0.0-stage → 0.4.0

package/lib/types/driver-core/session-model.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The dsh model selection a hosted engine is handed, and the ONE judgement that
+ * decides it.
+ *
+ * A session's model seat is the harness's own per-session fact: the host writes
+ * a `model/selection` event when the user picks a model, and derives the
+ * session's selection from the newest pending selection, else the logged
+ * `request/header` (`packages/api/session-controller/src/agent.ts`,
+ * `selectionFor`). A hosted engine owns its model natively, but it can still be
+ * handed a real dsh model when the session selected one — that is what this
+ * module answers.
+ *
+ * Three cases, decided once here and consumed by every hosted driver:
+ *
+ *  - NO selection, or one whose provider is a hosted engine route label
+ *    ({@link isHostedProviderRoute}: today's shared `external`, or a label an
+ *    earlier build logged) → `undefined`. The engine keeps its own native
+ *    default or the model the deployment pinned in its composition; nothing is
+ *    sent, so the engine is not asked a question it never had an opinion on.
+ *  - a REAL dsh model (any other provider) → `{ provider, model }`. Each engine
+ *    renders that into its own interface: Pi's `--model <provider>/<model>`,
+ *    Claude Code's `Options.model`, Codex's `thread/start` `model`, and Kimi's
+ *    ACP `session/set_model`. Whether the engine can actually serve the model is
+ *    the engine's own business: a refusal is reported, never swallowed.
+ *
+ * The read is the host's own ({@link currentSelection}), so the value an engine
+ * gets is the value the host would install for the session — and it is taken
+ * fresh on every step, because a session's model can change mid-conversation.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/session-model
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { HostedEngineId } from '../engine-registry.ts';
+import type { SessionModelSelection, SessionProjectionsService } from './host-servers.ts';
+/** The model a session's own selection asks a hosted engine to run. */
+export interface SessionModelOverride {
+    /** Provider route the selection names, in the engine's own provider vocabulary. */
+    readonly provider: string;
+    /** Provider-owned model id the selection names. */
+    readonly model: string;
+}
+/**
+ * The selection the host will use for this session, by the host's own read
+ * (`ApiSessionAgentController.selectionFor`): a pending selection — one
+ * appended, not yet consumed by a matching recorded request — outranks the
+ * logged header, and the header answers when nothing is pending.
+ *
+ * A deployment with no session-projection registry is not an error: the read
+ * simply skips the pending half and answers from the logged header, exactly as
+ * a session whose log carries only a header would.
+ * @param session - the session whose selection is being read.
+ * @param projections - the host session-projection registry, when composed.
+ * @returns the current selection, or undefined when the log records none.
+ */
+export declare function currentSelection(session: Session, projections: SessionProjectionsService | undefined): SessionModelSelection | undefined;
+/**
+ * The model one hosted engine should be handed for this selection, or
+ * `undefined` to leave the engine to its own default (or the deployment's pin).
+ *
+ * The provider is the whole test: a hosted engine route label — the shared
+ * `external` this plugin serves as a placeholder, or a per-engine label an
+ * earlier build logged — means "the engine decides", not a model to send. Any
+ * other provider is a real dsh model, and the plugin passes it through rather
+ * than second-guessing whether the engine can serve it: a rejection is the
+ * engine's to report, and this plugin surfaces it.
+ * @param selection - the session's current selection, or undefined when none.
+ * @returns the model to hand over, or undefined to send nothing.
+ */
+export declare function sessionModelOverride(selection: SessionModelSelection | undefined): SessionModelOverride | undefined;
+/**
+ * The model override for one session, read live from its log and judged by
+ * {@link sessionModelOverride}.
+ *
+ * The four drivers' single entry: each calls this at the top of every step, so a
+ * model picked mid-conversation lands on the engine's next request rather than
+ * being frozen when the agent was built.
+ * @param ctx - the driver's context, carrying the session-projection registry.
+ * @param session - the session whose selection is being resolved.
+ * @returns the model to hand the engine, or undefined to send nothing.
+ */
+export declare function sessionModelOverrideOf(ctx: Context, session: Session): SessionModelOverride | undefined;
+/**
+ * The ENGINE-NATIVE model one session's selection asks for, if any.
+ *
+ * A hosted engine's route normally answers `default`, meaning "the engine
+ * decides" — and {@link sessionModelOverride} correctly reports that as "send
+ * nothing". But an engine that declares its own catalog
+ * (`EngineDescriptor.models`) owns a route of its own, and selecting one of those
+ * entries names a model from the engine's own subscription. That is a third
+ * case, and it is NOT a dsh model: the id is the engine's vocabulary, so it must
+ * be handed over alone (`--model gemini-3.8-flash-high`), never as
+ * `provider/model`, and never routed through the endpoint handover.
+ *
+ * Kept beside {@link sessionModelOverride} rather than folded into it, so the
+ * four original drivers keep seeing exactly the answer they saw before.
+ * @param selection - the session's current selection, or undefined when none.
+ * @param engine - the engine this session is running.
+ * @returns the engine-native model id, or undefined when the selection is not one.
+ */
+export declare function nativeModelOf(selection: SessionModelSelection | undefined, engine: HostedEngineId): string | undefined;
+/**
+ * The refusal a driver owes when a session picked a model that belongs to a
+ * DIFFERENT engine, or undefined when the selection is fine.
+ *
+ * The model catalog is built per Host generation, so every engine's group is in
+ * every session's menu. Picking `agy`'s `gemini-3.8-flash-high` while the session
+ * runs Codex is therefore reachable, and silently ignoring it would leave the
+ * seat showing a model that is not in force — the exact class of lie this plugin
+ * exists to prevent. The driver refuses instead, naming both engines.
+ * @param selection - the session's current selection, or undefined when none.
+ * @param engine - the engine this session is running.
+ * @param engineLabel - that engine's display label, for the message.
+ * @returns the refusal message, or undefined.
+ */
+export declare function foreignHostedModelRefusal(selection: SessionModelSelection | undefined, engine: HostedEngineId, engineLabel: string): string | undefined;
+/**
+ * The model a driver should actually pass, resolved in one place.
+ *
+ * Three answers, in precedence order: an engine-native pick from this engine's
+ * own catalog; the deployment's pinned model; the engine's own default.
+ * @param selection - the session's current selection, or undefined when none.
+ * @param engine - the engine this session runs.
+ * @param pinned - the deployment's `model` knob for this engine, if any.
+ * @returns the model id to pass, or undefined to pass nothing.
+ */
+export declare function modelForStep(selection: SessionModelSelection | undefined, engine: HostedEngineId, pinned: string | undefined): string | undefined;
+//# sourceMappingURL=session-model.d.ts.map

package/lib/types/driver-core/skill-inject.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Skill-injection helpers shared by the hosted engine drivers. Each hosted
+ * engine's agent replicates the dsh `/name` skill gesture scan and the
+ * XML `<skill_content>` rendering that the in-process engine's dsh-tool-skill
+ * handler would otherwise provide — their agent contexts do not descend from
+ * the agent-preset chain. These helpers are pure: they take user messages or a
+ * loaded skill and return the injected text, with no session or loop access.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/skill-inject
+ */
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+export declare function isSkillName(name: string): boolean;
+/** Minimal shape of a loaded skill definition. */
+export interface SkillDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: {
+        readonly modelInvocable: boolean;
+        readonly userInvocable: boolean;
+    };
+    readonly source: string;
+    readonly provider: string;
+    readonly content: string;
+    readonly path?: string;
+    readonly resourceBase?: {
+        readonly kind: string;
+        readonly path: string;
+    };
+}
+/** Durable source for an injected user-explicit skill invocation (mirrors dsh-skill's). */
+export interface SkillInvocationSource {
+    readonly kind: 'skill-invocation';
+    readonly name: string;
+    readonly form: 'instructions';
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** A user-explicit skill invocation injected by this driver. */
+        'skill-invocation': SkillInvocationSource;
+    }
+}
+/** Minimal shape of the SkillRegistry service. */
+export interface SkillsService {
+    get(name: string, options: {
+        cwd?: string;
+        signal?: AbortSignal;
+        scope?: unknown;
+    }): Promise<SkillDefinition | undefined>;
+}
+/** Escape text for inclusion in XML-like skill markup. */
+export declare function escapeText(value: string): string;
+/** Escape an XML-like attribute value. */
+export declare function escapeAttr(value: string): string;
+/** Render the `<skill_content>` block for a loaded skill. */
+export declare function renderSkillContent(skill: SkillDefinition): string;
+/** Collect `/name` gesture tokens from direct user messages, in first-seen order. */
+export declare function invokedSkillNames(messages: readonly UserMessage[]): string[];
+//# sourceMappingURL=skill-inject.d.ts.map

package/lib/types/driver-core/step-close.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Closing one step of a hosted driver's transcript.
+ *
+ * A step may not end while a call it announced has no result (v4:
+ * `step/end leaves unresolved tool call …`), and an engine can leave one
+ * unanswered for reasons no driver controls — it announced several calls in one
+ * model turn and reported fewer outcomes, or the query ended mid-flight, or the
+ * step is aborting. The harness closes an interrupted turn the same way and with
+ * the same vocabulary (`openTurnClosers` in `@deepseek-ai/dsh-session/repair`):
+ * a synthetic ERROR result states the fact to the model, so the transcript stays
+ * valid and the next model turn knows the call's outcome is unknown rather than
+ * silently believing it succeeded.
+ *
+ * It is deliberately a closer, not a repair of history: it fixes the step being
+ * closed and nothing else.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/step-close
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { ToolCallId } from '@deepseek-ai/dsh-llm';
+import type { StepTools } from './step-tools.ts';
+/**
+ * End one step, closing every call it announced and never resolved.
+ *
+ * Synthetic results are appended BEFORE `step/end`, in announcement order, each
+ * citing nothing but its own call id — the driver has no `tool/call` event to
+ * cite because the call was announced by the assistant message that carried it.
+ * @param session - the session whose transcript is being written.
+ * @param tools - the step's call bookkeeping.
+ * @param turn - the turn the step belongs to.
+ * @param step - the step being closed.
+ */
+export declare function closeStep(session: Session, tools: StepTools, turn: number, step: number): void;
+/**
+ * Write one call's result, unless this step already has one for it.
+ *
+ * Every driver learns about a result from its engine's stream, and an engine can
+ * report the same outcome twice (the Claude Agent SDK redelivers each result
+ * ~57 ms later; Pi reports an execution from both `tool_execution_end` and its
+ * closing `turn_end`). v4 deletes a call's pending entry on its first result, so
+ * the second write is what it refuses (`tool/result … has no advertised tool
+ * lifecycle`) — the write goes through {@link StepTools.settle} instead, and the
+ * caller supplies only the durable write it would otherwise have made.
+ * @param tools - the step's call bookkeeping.
+ * @param callId - the call the result answers.
+ * @param write - the durable write, run at most once per call per step.
+ */
+export declare function settleResult(tools: StepTools, callId: ToolCallId, write: () => void): void;
+//# sourceMappingURL=step-close.d.ts.map

package/lib/types/driver-core/step-images.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The images one STEP hands to an engine that has a native image channel.
+ *
+ * The durable log is the model context, and a serialized prompt can only carry
+ * an image as placeholder text naming the file ({@link serializeHistory}). An
+ * engine whose protocol accepts image bytes should not be told to read the file
+ * itself: {@link stepImages} resolves each image block of the step's own
+ * messages through the attachment service's host path, reads that normalized
+ * file, and returns it base64-encoded under the block's own media type. An
+ * engine whose protocol takes the file's PATH instead shares the walk and the
+ * resolution but reads nothing ({@link stepImagePaths}) — codex's app-server
+ * opens the image itself.
+ *
+ * Only the messages this step delivers are claimed — a long session must not
+ * re-upload its whole history every step. Older images stay in the transcript
+ * as path-bearing placeholders, which the engine's own file tool can still read.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/step-images
+ */
+import type { ContentBlock, ImageAttachmentAccessResolver, Message } from '@deepseek-ai/dsh-llm';
+/** The durable reference an image block carries, derived from the block union so this module states no dependency on the attachment package. */
+type ImageBlock = Extract<ContentBlock, {
+    type: 'image';
+}>;
+/**
+ * The media types a durable image reference can carry, taken from the block
+ * union so this module names no attachment-package symbol. It is the exact set
+ * every byte-accepting engine protocol declares (Anthropic's base64 image
+ * source among them), so a caller may hand this value straight to one.
+ */
+type ImageMediaType = ImageBlock['attachment']['mediaType'];
+/** One image of a step, as an engine that accepts image bytes takes it. */
+export interface StepImage {
+    /** Base64-encoded normalized bytes. */
+    readonly data: string;
+    /** The image's own media type, from the durable reference. */
+    readonly mimeType: ImageMediaType;
+}
+/**
+ * Collect the images a step's messages carry, in message order.
+ *
+ * An image whose path does not resolve, or whose file cannot be read, is
+ * skipped: the transcript already names its path, so the model still has a route
+ * to it, and one missing file must not fail a step.
+ * @param messages - the messages this step delivers, oldest first.
+ * @param imageAccess - resolves an image block's read-only host path, when the host composes the attachment service.
+ * @returns the images to send, empty when there are none.
+ */
+export declare function stepImages(messages: readonly Message[], imageAccess?: ImageAttachmentAccessResolver): Promise<readonly StepImage[]>;
+/**
+ * The readable host path of each image the step delivers, in order.
+ *
+ * Nothing is opened: an engine that takes a path reads the file itself, so a
+ * path is returned even when no file is there — whether the path is usable is
+ * the engine's answer, not this walk's.
+ * @param messages - the messages this step delivers, oldest first.
+ * @param imageAccess - resolves an image block's read-only host path, when the host composes the attachment service.
+ * @returns the paths to send, empty when there are none.
+ */
+export declare function stepImagePaths(messages: readonly Message[], imageAccess?: ImageAttachmentAccessResolver): readonly string[];
+export {};
+//# sourceMappingURL=step-images.d.ts.map

package/lib/types/driver-core/step-tools.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The tool calls one STEP has announced, and which of them already carry a
+ * result.
+ *
+ * Session format v4 requires every call a step announced to be resolved before
+ * that step ends (`step/end leaves unresolved tool call …`,
+ * `packages/session/session-format-v3-to-v4/src/relationships.ts`). A hosted
+ * driver learns about calls from the engine's stream, one assistant message at
+ * a time, and learns about results from a different stream of messages — so
+ * "which calls of THIS step are still open" is state the driver has to keep,
+ * not something the transcript position can be trusted to imply.
+ *
+ * Two facts live here, and they are the two directions of the same rule:
+ * `settle` keeps a call from being given a SECOND result in one step (the
+ * shape v4 rejects as `tool/result … has no advertised tool lifecycle`), and
+ * {@link StepTools.pending} is what a step must close before it ends.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/step-tools
+ */
+import type { ToolCallId } from '@deepseek-ai/dsh-llm';
+/** One step's announced calls and their results. */
+export interface StepTools {
+    /** Record a call this step announced. */
+    announce(callId: ToolCallId): void;
+    /**
+     * Record a result this step wrote.
+     * @returns `false` when that call was already settled in this step, i.e.
+     *   when writing another result for it would be the duplicate v4 refuses.
+     */
+    settle(callId: ToolCallId): boolean;
+    /** Whether every call this step announced now has a result. */
+    readonly balanced: boolean;
+    /** The calls still owed a result, in the order they were announced. */
+    readonly pending: readonly ToolCallId[];
+    /** Forget everything: the next step owns a new set. */
+    clear(): void;
+}
+/**
+ * Build one step's call bookkeeping.
+ * @returns the set, empty and ready for its step.
+ */
+export declare function createStepTools(): StepTools;
+//# sourceMappingURL=step-tools.d.ts.map

package/lib/types/driver-core/system-head.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Give a session started on a hosted engine the protected system head the
+ * harness's own loop would have logged.
+ *
+ * The harness loop logs the rendered system prompt as a `system/message` on a
+ * session's first step (`packages/core/agent-loop/src/agent.ts`:
+ * `systemPrompt.project` → `session.append('system/message', …)`). A hosted
+ * engine's external CLI owns its own system prompt, so these drivers log no dsh
+ * system message at all: a session that STARTS on a hosted engine has no surface
+ * head, and if it is later served by the in-process loop the harness logs its
+ * system message MID-log. Session format v4 requires the system message — when
+ * one exists — to be the FIRST surface event, so such a mixed session is refused
+ * on the v3→v4 migration (`packages/session/session-format-v3-to-v4/src/
+ * relationships.ts` `foldSurface`: "system/message requires a protected first
+ * surface head").
+ *
+ * Appending an EMPTY system message as the session's first surface event closes
+ * that hole: the head is protected from the start (a later in-process system
+ * message REPLACES it rather than arriving misplaced), and empty content is
+ * dropped from the derived history (`deriveEventMessage` yields `null`), so no
+ * system prompt is injected into what the engine is handed — the drivers build
+ * their prompt from `serializeHistory`, which ignores the `system` role too.
+ *
+ * Conservative and idempotent: it appends ONLY while the session has no surface
+ * event of its own, so a session the harness loop created (or one already
+ * carrying history) is left exactly as it is. A mid-surface system head would be
+ * refused by the SAME v4 rule and is never produced here.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/system-head
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+/**
+ * Append an empty `system/message` head when the session has no surface event
+ * yet, so a hosted-engine session carries the protected head format v4 expects.
+ *
+ * A no-op once any surface event exists: the head can only ever be the FIRST
+ * surface event, and a later one would be refused on migration.
+ * @param session - the session a hosted driver is about to run a step on.
+ * @param turn - the open turn's number.
+ * @param step - the open step's number.
+ */
+export declare function appendSystemHeadIfMissing(session: Session, turn: number, step: number): void;
+//# sourceMappingURL=system-head.d.ts.map

package/lib/types/engine-agy/agent.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Antigravity agent: one `agy --input-format stream-json --output-format
+ * stream-json --print=` child per dsh step, with the durable session log as the
+ * sole source of model context.
+ *
+ * The engine-specific surface is `runStep`: serialize the transcript, write it to
+ * the child's stdin as one NDJSON user message, decode the `event`-tagged reply
+ * stream, and let the shared sink write the durable log. See
+ * `./process.ts` for the argument-position trap that shapes the argv and for the
+ * one protocol fact the probe could not reach (a signed-in host was unavailable),
+ * and `./frames.ts` for how the mapper stays correct under both worlds.
+ *
+ * @module dsh-loop-engine-allinone/engine-agy/agent
+ */
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { HostedEngineId } from '../engine-registry.ts';
+import { CliHostedAgent } from '../driver-cli/cli-agent.ts';
+import type { SinkPosition } from '../driver-cli/session-sink.ts';
+import type { CliSpawnCapability } from '../driver-cli/transport.ts';
+import type { AgyEffort, AgyMode } from './process.ts';
+/** Deployment-resolved configuration for the Antigravity engine. */
+export interface ResolvedAgyConfig {
+    /** Pinned auto-approve flag, overriding the session's dsh knobs. */
+    readonly dangerouslySkipPermissions: boolean | undefined;
+    /** Pinned executable, when the deployment named one. */
+    readonly bin: string | undefined;
+    /** Explicit environment entries layered over the scrubbed parent environment. */
+    readonly env: Record<string, string>;
+    /** Pinned model. */
+    readonly model: string | undefined;
+    /** Pinned execution mode. */
+    readonly mode: AgyMode | undefined;
+    /** Pinned reasoning effort. */
+    readonly effort: AgyEffort | undefined;
+    /** Pinned sandbox flag, overriding the session's knobs. */
+    readonly sandbox: boolean | undefined;
+}
+/** The engine id this driver registers under. */
+export declare const AGY_ENGINE: HostedEngineId;
+/** Drives one session through turn and step boundaries on Antigravity. */
+export declare class AgyAgent extends CliHostedAgent {
+    private readonly config;
+    private readonly spawn;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedAgyConfig, spawn: CliSpawnCapability);
+    protected runStep(messages: readonly UserMessage[], position: SinkPosition, signal: AbortSignal): Promise<{
+        kind: 'completed';
+    } | null>;
+    /**
+     * The session's current model selection, read the way the host reads it.
+     * @returns the selection, or undefined when the log records none.
+     */
+    private selection;
+    /**
+     * Whether the child should run with terminal restrictions (`--sandbox`).
+     *
+     * Antigravity's `--sandbox` restricts the CLI's own terminal use, which is not
+     * the same thing as the permission switch (see
+     * `agyDangerouslySkipPermissions`). It is requested whenever the session is NOT
+     * at full access: the subprocess seam already bounds the child, and asking the
+     * CLI to restrict itself as well is the fail-closed direction.
+     * @returns whether to pass `--sandbox`.
+     */
+    private sandboxRequested;
+}
+//# sourceMappingURL=agent.d.ts.map

package/lib/types/engine-agy/frames.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The Antigravity frame mapper — now written against REAL frames.
+ *
+ * The first version of this module was written while the probe host's Google
+ * credential was expired, so only the `result` envelope could be observed and
+ * the streaming vocabulary was left UNKNOWN. Re-probing after the host signed in
+ * produced the whole protocol, and this is that protocol:
+ *
+ * ```
+ * {"event":"init","conversation_id":"f3b26f65-…",
+ *  "init":{"cwd":"…","tools":[…],"permission_mode":"request-review"}}
+ *
+ * {"event":"step_update","step_update":{
+ *   "conversation_id":"…","step_index":1,"state":"ACTIVE",
+ *   "step_type":"agent_response","text_delta":"Source code turns to byt"}}
+ * {"event":"step_update","step_update":{
+ *   "conversation_id":"…","step_index":1,"state":"DONE","step_type":"agent_response",
+ *   "text_delta":"\n","duration_seconds":8.2,
+ *   "usage":{"input_tokens":11707,"output_tokens":881,"thinking_tokens":864,
+ *            "cache_read_tokens":0,"total_tokens":12588}}}
+ *
+ * {"event":"step_update","step_update":{
+ *   "conversation_id":"…","step_index":2,"state":"ACTIVE","step_type":"tool",
+ *   "tool_name":"run_command","tool_info":{"name":"run_command",
+ *     "parameters":{"CommandLine":"echo hi"}}}}
+ * {"event":"step_update","step_update":{
+ *   "conversation_id":"…","step_index":2,"state":"DONE","step_type":"tool",
+ *   "tool_name":"run_command","duration_seconds":0.75,
+ *   "tool_info":{"name":"run_command","parameters":{"CommandLine":"echo hi"},
+ *                "output":"hi\r\n"}}}
+ *
+ * {"event":"result","result":{"conversation_id":"…","status":"SUCCESS",
+ *   "response":"Source code turns to bytes,\nSyntax checked and optimized,\nSilicon wakes up.\n",
+ *   "duration_seconds":…,"num_turns":…,"usage":{…}}}
+ * ```
+ *
+ * ## The four things this shapes
+ *
+ *  1. **`step_update` is the universal frame.** `step_type` says what the update
+ *     is about — `user_input` (the echo of what we sent), `agent_response`
+ *     (streamed answer text) or `tool` (an announced call, then its result) — and
+ *     `state` says whether it is ACTIVE (in flight) or DONE (settled).
+ *  2. **Answer text streams.** `text_delta` arrives incrementally on ACTIVE
+ *     frames, and `result.response` repeats the concatenation at the end. Both
+ *     are read; the envelope is emitted ONLY when no delta ever arrived, so the
+ *     answer cannot land twice.
+ *  3. **Tool calls need a synthesized id.** The protocol carries NO call id — a
+ *     tool is identified by its `step_index` inside the conversation. dsh keys
+ *     its pending-tool map by id and requires exactly one result per id, so the
+ *     id is built as `<conversation_id>-tool-<step_index>`, which is unique
+ *     because every driver run opens a fresh conversation (the driver never
+ *     passes `--conversation`).
+ *  4. **A tool result carries no error flag.** `tool_info` has `name`,
+ *     `parameters` and `output`; a failure is read from an `error` member when
+ *     one appears and otherwise treated as a success, because inventing a
+ *     failure would be worse than reporting a successful-but-empty one.
+ *
+ * Anything unrecognized is dropped, which is what lets a protocol that grows a
+ * new event keep working. The one rule that is NOT best-effort: a `result` whose
+ * status is not success is reported as a failure carrying the CLI's own words,
+ * because a failed run must never read as an empty answer.
+ *
+ * @module dsh-loop-engine-allinone/engine-agy/frames
+ */
+import type { CliFrame } from '../driver-cli/frames.ts';
+/** What the mapper learned about the run beyond its frames. */
+export interface AgyRun {
+    /** The conversation id the CLI reported, when it reported one. */
+    conversationId: string | undefined;
+    /**
+     * Whether the streamed deltas already delivered the answer.
+     *
+     * The `result` envelope repeats the whole response, so this is what keeps the
+     * answer from being committed twice.
+     */
+    answered: boolean;
+    /** The last `agent_response` step index a segment was opened for. */
+    openStep: number | undefined;
+}
+/** Create a fresh run accumulator. */
+export declare function newAgyRun(): AgyRun;
+/**
+ * Map one parsed Antigravity document to frames.
+ * @param document - the parsed document.
+ * @param accept - frame sink.
+ * @param run - the run accumulator, updated in place.
+ * @returns the frames to accept — empty, because this mapper pushes directly.
+ */
+export declare function mapAgyDocument(document: unknown, accept: (frame: CliFrame) => void, run: AgyRun): readonly CliFrame[];
+//# sourceMappingURL=frames.d.ts.map

package/lib/types/engine-agy/loop.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Antigravity loop engine module: drives every session it is handed through one
+ * `agy` stream-json child per dsh step, with the durable session log as the sole
+ * source of model context. The router routes a session here on the plugin's own
+ * engine record, else its agent preset; this module is a library, not a Cordis
+ * plugin entry.
+ *
+ * Authentication is entirely the CLI's: the plugin never reads, writes or
+ * refreshes Antigravity's Google credential — the child inherits the standard
+ * user environment and finds it itself, which is what makes a session run on the
+ * user's own subscription rather than on any credential this plugin holds.
+ *
+ * @module dsh-loop-engine-allinone/engine-agy
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { CliEngineRuntime } from '../driver-cli/cli-loop.ts';
+import { AgyAgent, type ResolvedAgyConfig } from './agent.ts';
+import type { AgyEffort, AgyMode } from './process.ts';
+/** Deployment-owned configuration for the Antigravity engine. */
+export interface Config {
+    /** Model for the CLI (`--model`); Antigravity's own settings own the model when omitted. */
+    model?: string;
+    /** Explicit environment entries passed to the child. */
+    env?: Record<string, string>;
+    /** The `agy` executable; the CLI's own install location (and PATH) when not pinned. */
+    bin?: string;
+    /** The execution mode (`--mode`); omitted lets the CLI use its own default. */
+    mode?: AgyMode;
+    /** Reasoning effort (`--effort`). */
+    effort?: AgyEffort;
+    /** Pinned terminal-restriction flag, overriding the session's permission knobs. */
+    sandbox?: boolean;
+    /**
+     * Pinned auto-approve flag (`--dangerously-skip-permissions`), overriding the
+     * session's sandbox knob.
+     *
+     * Set this to `true` to give Antigravity the same room as
+     * `danger-full-access` without changing the session's own permission preset.
+     */
+    dangerouslySkipPermissions?: boolean;
+}
+/** Schema of the Antigravity engine configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const AGY_ENGINE_LABEL = "agentLoopAgy";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopAgy: AgyLoop;
+    }
+}
+/**
+ * Creation/resume machinery for the Antigravity engine. The process-wide
+ * AgentFactory slot belongs to the router, which delegates each session to the
+ * engine its preset names; this class is that engine's driver, not a plugin.
+ */
+export declare class AgyLoop extends CliEngineRuntime<ResolvedAgyConfig, AgyAgent> {
+    constructor(ctx: Context, config: Config);
+    /** Construct the Antigravity driver for one prepared session. */
+    protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): AgyAgent;
+}
+//# sourceMappingURL=loop.d.ts.map