dsh-pstack 0.1.0 → 0.2.0-beta.1

package/dist/script.d.mts

@@ -0,0 +1,193 @@
+import { a as JobsHost, g as ToolDefinition, i as JobId, o as JsonSchemaNode, u as SessionId, v as ToolsHost, y as WorkingDirectoryHost } from "./host-contract-o47JH_r8.mjs";
+//#region src/script.d.ts
+/** Model-facing tool name. */
+export declare const TOOL_NAME = "pstack_script";
+/** The shipped scripts this tool may run, in display order. */
+export declare const SCRIPT_IDS: string[];
+export type ScriptId = (typeof SCRIPT_IDS)[number];
+/** Default wall-clock limit for a foreground run. */
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+/** Bounds a caller may set for one foreground run. */
+export declare const MAX_TIMEOUT_MS = 600000;
+/** Default cap on captured bytes per stream. */
+export declare const DEFAULT_OUTPUT_LIMIT_BYTES: number;
+/** Raised for an argument problem, before anything is spawned. */
+export declare class ScriptInputError extends Error {
+  constructor(message: string);
+}
+/** Raised when a shipped artefact is missing from this install. */
+export declare class ScriptMissingError extends Error {
+  constructor(message: string);
+}
+/** One parsed call. */
+export interface ScriptArgs {
+  readonly id: ScriptId;
+  readonly args: readonly string[];
+  readonly cwd?: string;
+  readonly background: boolean;
+  readonly timeoutMs?: number;
+  readonly outputLimitBytes?: number;
+}
+/** What a foreground run produced. */
+export interface ScriptResult {
+  readonly kind: "foreground";
+  readonly id: ScriptId;
+  readonly exitCode: number;
+  readonly signal: NodeJS.Signals | null;
+  readonly timedOut: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+  /** True when a stream was cut off at the limit. */
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
+  readonly durationMs: number;
+}
+/** What a background run produced. */
+export interface ScriptJobResult {
+  readonly kind: "background";
+  readonly id: ScriptId;
+  readonly jobId: JobId;
+  readonly status: string;
+}
+/** Either outcome, as the model sees it. */
+export type ScriptOutcome = ScriptResult | ScriptJobResult;
+/** Absolute path of one shipped artefact. */
+export declare function scriptPath(id: ScriptId): string;
+/**
+ * The environment a child gets.
+ *
+ * The one rule is the Electron selector. Under Electron, `process.execPath` is the
+ * Desktop binary, which starts a browser window unless `ELECTRON_RUN_AS_NODE=1` tells
+ * it to behave as Node. Under plain Node the variable is inert — Node ignores it —
+ * so setting it unconditionally would also work; it is conditional here so the
+ * environment of a normal run stays exactly the caller's, and the one code path that
+ * needs it is visible.
+ */
+export declare function scriptEnvironment(base?: NodeJS.ProcessEnv, versions?: {
+  readonly electron?: string;
+}): NodeJS.ProcessEnv;
+/** Validate the raw tool arguments. */
+export declare function parseScriptArgs(raw: unknown): ScriptArgs;
+/**
+ * Resolve the directory the child runs in.
+ *
+ * The tool's `cwd` argument is documented as resolving against "this session's
+ * directory", so `sessionCwd` — the value `ctx.workingDirectory.ensure()` returns —
+ * is the base, not the Host process's working directory.
+ *
+ * - omitted           -> the session directory
+ * - relative          -> joined onto the session directory
+ * - absolute          -> used as-is
+ *
+ * With no Session (a call outside an Agent) there is no session directory to
+ * anchor to; the argument is then passed through and `resolve` normalises it
+ * against the Host process, which is the only directory that exists.
+ */
+export declare function resolveWorkingDirectory(requested: string | undefined, sessionCwd: string | undefined): string | undefined;
+/**
+ * Run one script in the foreground.
+ *
+ * A nonzero exit, a signal, a timeout, and truncated output are all returned rather
+ * than raised: the caller needs to see what the script said before it failed, and an
+ * exception would discard the captured output.
+ */
+export declare function runForeground(args: ScriptArgs, options?: {
+  readonly execPath?: string;
+  readonly environment?: NodeJS.ProcessEnv;
+  /** Already resolved by the caller; see `resolveWorkingDirectory`. */
+  readonly cwd?: string;
+  readonly signal?: AbortSignal;
+}): Promise<ScriptResult>;
+/**
+ * Start a script as a background job.
+ *
+ * `jobs` is required and passing nothing is a refusal with a reason. A job whose
+ * output nobody can read would be worse than a failed call: the model would report a
+ * task as started and no notice would ever arrive.
+ */
+export declare function runBackground(args: ScriptArgs, options: {
+  readonly jobs?: JobsHost | undefined;
+  readonly caller?: SessionId;
+  readonly execPath?: string;
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly cwd?: string;
+}): Promise<ScriptJobResult>;
+/**
+ * Render one captured stream as a fenced block, byte for byte.
+ *
+ * `trimEnd` used to run here, which is wrong for two reasons:
+ *
+ * - A stream of only whitespace passed the `!== ""` test and then rendered as an
+ *   empty-looking `stdout:` line, so a reader concluded the script printed nothing.
+ * - `check-plan`'s contract includes exact line counts and blank-line separators, so
+ *   a trimmed block is a different document — and the model reads this text as the
+ *   script's output.
+ *
+ * A fence keeps every byte visible, including trailing blank lines. The fence is
+ * lengthened past the longest backtick run in the content so it can never be closed
+ * early by the content itself. Nothing inside is escaped or reinterpreted.
+ */
+export declare function renderCapturedStream(text: string): readonly string[];
+/** Render one outcome for the model. */
+export declare function renderScriptOutcome(outcome: ScriptOutcome): string;
+/** The model-facing JSON Schema for `parameters`. */
+export declare function buildScriptParameters(): Record<string, unknown>;
+/**
+ * The declared shape of one outcome, exported so tests can validate real results.
+ *
+ * Split by `kind` instead of one flat object. The flat form could only require
+ * `kind` and `id`, so a foreground result that omitted `exitCode` was still
+ * "valid" and the schema proved nothing about the fields the model reads.
+ *
+ * `signal` is nullable because `child_process` reports `null` whenever the child
+ * exited on its own — that is every successful run. Declaring it `string` made
+ * the registry reject the tool's own normal output: `createSuccessResult()`
+ * validates before rendering, so **every** clean exit surfaced to the model as
+ * `tool "pstack_script" returned invalid output`.
+ */
+export declare const OUTPUT_SCHEMA: JsonSchemaNode;
+/** The slices of the Cordis context this tool needs. */
+export interface PstackScriptHost {
+  readonly tools: ToolsHost;
+  /** Resolves the Session's current directory; see `WorkingDirectoryHost`. */
+  readonly workingDirectory: WorkingDirectoryHost;
+  /**
+   * Optional, and read per call rather than snapshotted.
+   *
+   * A profile may mount a job controller after this row, so a value read once in
+   * `apply` would stay `undefined` forever. `ctx.get("jobs")` is rc.3's
+   * optional-service read: it returns `undefined` instead of throwing when the
+   * service is absent, which is why `jobs` is not declared in `inject`.
+   */
+  readonly getJobs?: () => JobsHost | undefined;
+}
+/** Build the tool for one row. */
+export declare function createPstackScriptTool(host: PstackScriptHost): ToolDefinition;
+/** Cordis row name, used by Loader diagnostics. */
+export declare const name = "pstack-script";
+/**
+ * The hard dependencies.
+ *
+ * `tools` is the registry this row registers into; `workingDirectory` is what
+ * turns the tool's `cwd` argument and its omitted case into the Session's
+ * directory. Both are always present in a profile that has an Agent at all.
+ *
+ * `jobs` is deliberately absent: a composition without a job controller still
+ * registers the tool, and only `background: true` is refused. Declaring `jobs`
+ * here would keep the whole fiber inactive in every profile that has no job
+ * controller, which is most of them.
+ */
+export declare const inject: string[];
+/**
+ * Register `pstack_script` for this row.
+ *
+ * `inject` is what makes `ctx.tools` readable at all: without it Cordis runs
+ * `apply` immediately and the service proxy throws
+ * `cannot get property "tools" without inject`, so the row would register nothing
+ * in any profile.
+ */
+export declare function apply(ctx: PstackScriptHost & {
+  get?: (name: string) => JobsHost | undefined;
+}): void;
+//#endregion
+//# sourceMappingURL=script.d.mts.map