wingfoil 0.2.1 → 0.3.0

package/dist/agent/execute.d.ts

@@ -0,0 +1,206 @@
+import type { AgentEntry, DnaYaml } from '../dna/schema';
+import { type ExecutionContextElement } from '../core/context';
+import { type CoreResult } from '../core/types';
+import type { LaunchHost } from './launch';
+import { type LoadedAdapter } from './discovery';
+import { type StepSelector } from './step';
+/** The role of a run with no step and no `--role` (`X_cli-cmds.md:223`, approver ruling R18). */
+export declare const DEFAULT_ROLE: "developer";
+/** The warning that says the role was defaulted (§3.2 step 3). */
+export declare const DEFAULT_ROLE_WARNING: string;
+/** The mode that runs: `fresh`, the only one in v0.3 (§3.2 step 6). */
+export declare const FRESH_MODE: "fresh";
+/** How long the MCP pre-flight may take, start-up included, before it counts as unreachable. */
+export declare const MCP_PREFLIGHT_TIMEOUT_MS = 30000;
+/** P5.4.3 sc. 3, verbatim (§3.7 `MCP_UNREACHABLE`). */
+export declare const MCP_UNREACHABLE_MESSAGE = "context pre-load failed: MCP server unreachable";
+/**
+ * §2.4's `{handoff_line}`: the section line when the element type's template has a `## Execution
+ * Notes` heading line, the fallback otherwise.
+ */
+export declare function handoffLine(templateHasExecutionNotes: boolean): string;
+/** What the bootstrap is a function of (§2.4), plus the handoff line its type template selects. */
+export interface BootstrapInput {
+    readonly role: string;
+    /** `<type>:<id>`. */
+    readonly element: string;
+    readonly runId: string;
+    /** The full sha the context is assembled at. */
+    readonly stateRef: string;
+    /** {@link handoffLine}'s answer for the element's type. */
+    readonly handoff: string;
+    /**
+     * The `team.agents` entry that runs and signs the agent's commits (`dl-158` Rule 1 (a)): its `name`
+     * and `email`, which the attribution line hands to the agent (`dl-117` Action 4, ruling R20 Q8).
+     */
+    readonly agent: {
+        readonly name: string;
+        readonly email: string;
+    };
+}
+/** The fixed opening of §2.4's attribution line (task-228, `git-conventions` §7). */
+export declare const ATTRIBUTION_LINE_PREFIX = "End every commit you write, except an approve or reject commit, with the trailer paragraph";
+/** §2.4's attribution line for `agent`: the rule of `git-conventions` §7, with the entry that signs. */
+export declare function attributionLine(agent: {
+    readonly name: string;
+    readonly email: string;
+}): string;
+/**
+ * The bootstrap prompt (§2.4): the only text WingFoil puts into the agent's initial prompt. Pure, with
+ * no clock and no host data, LF-terminated. Its last line hands the agent the attribution rule and the
+ * entry that signs (task-228). A change to any literal here is a revision of `spec-016`.
+ */
+export declare function renderBootstrap(input: BootstrapInput): string;
+/** An MCP server to start: an executable and its argv, never a shell line. */
+export interface McpServerCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+/**
+ * The server `agent execute` registers and pre-flights (§2.5): the build that is running it — the Node
+ * executable, and `[<that build's cli.js>, "mcp"]`, `cli.js` sitting one directory above this module in
+ * the compiled layout (`dist/agent/` → `dist/cli.js`).
+ */
+export declare function runningBuildMcpServer(): McpServerCommand;
+/**
+ * Render `mcp.template` (§2.3): `{mcp_command}` becomes the executable as JSON string content (the
+ * template quotes it; a quote or a backslash in the path stays valid), `{mcp_args}` the argv as a JSON
+ * array. The manifest validator admits no other placeholder there, so any other token is left as is.
+ */
+export declare function renderMcpTemplate(template: string, server: McpServerCommand): string;
+/** The temporary files a launch may need (§2.3), by the placeholder that names each one's path. */
+export type RunFileName = 'bootstrap_file' | 'mcp_config_file';
+/**
+ * Write `files` into a fresh directory of the operating system's temporary directory (never the
+ * repository, §2.3), owner-only, run `work` with their absolute paths, and remove the directory when
+ * `work` settles — resolved, rejected or thrown alike.
+ *
+ * A `SIGINT`, `SIGTERM` or `SIGHUP` that arrives meanwhile (a pre-flight interrupted from the keyboard,
+ * task-218's review) removes the directory too, then ends the process by that same signal. `work`
+ * receives `release`, which removes that handling: the launch calls it when it takes the signals over
+ * (§3.3 step 15).
+ */
+export declare function withRunFiles<T>(files: Partial<Record<RunFileName, string>>, work: (paths: Partial<Record<RunFileName, string>>, release: () => void) => Promise<T>): Promise<T>;
+/**
+ * §3.3 step 4: whether the adapter's `command` can be started — a name holding no path separator is
+ * looked up on `searchPath` (`PATH`), in order; anything else is a path, resolved against the project
+ * root when relative. Either way it must be an executable regular file. Nothing is run, and no shell is
+ * involved (`dl-090` Q3 (a)).
+ */
+export declare function agentCommandFound(root: string, command: string, searchPath: string | undefined): boolean;
+/**
+ * §3.2 step 4 (the role already checked): with `agentName`, that `team.agents` entry, which must
+ * execute `role` and declare an `adapter`; without it, the first entry in declared order that does both.
+ */
+export declare function selectAgent(dna: DnaYaml, role: string, agentName: string | undefined): CoreResult<AgentEntry>;
+/** What {@link mcpPreflight} needs. */
+export interface McpPreflightInput {
+    readonly root: string;
+    readonly server: McpServerCommand;
+    readonly role: string;
+    /** `<type>:<id>`. */
+    readonly element: string;
+    readonly stateRef: string;
+    readonly timeoutMs: number;
+}
+/**
+ * §3.3 step 11: start the server, complete MCP `initialize`, get the `{role}-session` Prompt with
+ * `element` and `state`, read the session Resource the bootstrap names (§2.4, task-236), and close. The
+ * project's own registration (`.mcp.json`) is not read (§2.5). Any failure — the server does not start,
+ * exits, refuses the Prompt or the Resource, returns no text, or exceeds `timeoutMs` — is `IO` with
+ * P5.4.3 sc. 3's message verbatim, its cause as a `dl-055` detail line with the project root removed.
+ *
+ * Both carriers are checked, the Prompt first: the agent reads the Resource, and the Prompt serves the same
+ * text to a client that gets Prompts; one deadline covers the whole exchange.
+ */
+export declare function mcpPreflight(input: McpPreflightInput): Promise<CoreResult<undefined>>;
+/**
+ * The request (§3.1): `--element`, `--role`, `--agent`, and, for a step form, the step selector. At least one
+ * of `element` and `step` is given (the caller's usage check, §3.1).
+ */
+export interface AgentExecuteRequest {
+    /** `--element`; with a step form it overrides the step's element and keeps its phase and role. */
+    readonly element?: ExecutionContextElement;
+    /** `--next`, `--workflow <ref>`, `--step <key>` (task-235): present for a step form, even empty (`--next`). */
+    readonly step?: StepSelector;
+    /**
+     * `--role`; absent → the step's role (a step form), else {@link DEFAULT_ROLE} with
+     * {@link DEFAULT_ROLE_WARNING}.
+     */
+    readonly role?: string;
+    /** `--agent`; absent → the first agent with an adapter that executes the role. */
+    readonly agent?: string;
+}
+/** The host facts the pipeline reads, each overridable by a caller (tests) and defaulted from the process. */
+export interface AgentExecuteHost extends LaunchHost {
+    /** The server the pre-flight starts; {@link runningBuildMcpServer} by default. */
+    readonly mcpServer?: McpServerCommand;
+    /** Whether stdin and stdout are both terminals (§3.3 step 12); the process's own by default. */
+    readonly isTerminal?: () => boolean;
+    /** The `PATH` step 4 searches; `process.env.PATH` by default. */
+    readonly searchPath?: string;
+    /** {@link MCP_PREFLIGHT_TIMEOUT_MS} by default. */
+    readonly mcpTimeoutMs?: number;
+}
+/** A launch every pre-launch check has passed: what step 13 on needs. */
+export interface PreparedLaunch {
+    readonly runId: string;
+    /** `<type>:<id>`. */
+    readonly element: string;
+    readonly workflow: string;
+    readonly phase: string;
+    readonly role: string;
+    readonly mode: string;
+    /** The `team.agents` entry that runs, and signs its commits (`dl-158` Rule 1 (a)). */
+    readonly agent: AgentEntry;
+    readonly adapter: LoadedAdapter;
+    /** The full sha everything was read at. */
+    readonly stateRef: string;
+    /** Root-relative path of the run-log file the record will be committed to. */
+    readonly logPath: string;
+    /** Root-relative path of the element's document at `state_ref` (the record's `notes`, §4.2 key 18). */
+    readonly elementPath: string;
+    /** Root-relative path of the element type's template file, when the type declares one. */
+    readonly templatePath: string | undefined;
+    /** §2.4's bytes. */
+    readonly bootstrap: string;
+    /** The server the agent is registered with (§2.5). */
+    readonly mcpServer: McpServerCommand;
+    /** Absolute paths of the temporary files (§2.3), valid until the launch callback settles. */
+    readonly files: Partial<Record<RunFileName, string>>;
+    /** The rendered `mcp.template` under `mcp.via: config-arg` (§2.3 `{mcp_config}`); `undefined` otherwise. */
+    readonly mcpConfig?: string | undefined;
+}
+/**
+ * Run `agent execute`'s pipeline up to the spawn (§3.3 steps 2–12, see the module doc), then
+ * `launch` with the prepared launch, while its temporary files exist. Warnings go through the warning
+ * sink as they arise. Returns the first refusal, or what `launch` returns.
+ *
+ * @param root - The project root, already known to be initialized.
+ */
+export declare function agentExecutePipeline<T>(root: string, request: AgentExecuteRequest, host: AgentExecuteHost, launch: (prepared: PreparedLaunch, releaseSignals: () => void) => Promise<CoreResult<T>>): Promise<CoreResult<T>>;
+/** The launch `--dry-run` prints (`spec-008` §2): the record commit it would make, and the run. */
+export interface AgentLaunchPlan {
+    readonly dryRun: true;
+    /** `agent: record <run-id>`. */
+    readonly subject: string;
+    /** The run-log file the record commit would hold. */
+    readonly paths: readonly string[];
+    /** The record's fields known before the spawn, in §4.2 order. */
+    readonly run: {
+        readonly id: string;
+        readonly element: string;
+        readonly workflow: string;
+        readonly phase: string;
+        readonly role: string;
+        readonly mode: string;
+        readonly agent: string;
+        readonly adapter: string;
+        readonly state_ref: string;
+    };
+    /** §2.4's bootstrap, the bytes the agent would be given. */
+    readonly bootstrap: string;
+}
+/** The plan of `prepared` (a pure function of it, host paths excluded). */
+export declare function launchPlan(prepared: PreparedLaunch): AgentLaunchPlan;
+//# sourceMappingURL=execute.d.ts.map

package/dist/agent/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/agent/execute.ts"],"names":[],"mappings":"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"}