@poe-platform/safe-js 0.1.0

package/dist/agent-harness-tools/poe-command-execution.d.ts

@@ -0,0 +1,37 @@
+import { type RunnerScope, type ResolvedConfig, type StateManager } from "../poe-code-config/index.js";
+import { selectExecutionEnv, type OpenSpec } from "./execution-env.js";
+export type RuntimeOverrideOptions = {
+    runtime?: "host" | "docker";
+    runtimeImage?: string;
+    detach?: boolean;
+    mountPoeCode?: boolean;
+    runnerSync?: RunnerScope["sync"];
+};
+export declare function resolvePoeCommandExecution(input: {
+    cwd: string;
+    runtimeConfigCwd?: string;
+    env: Record<string, string>;
+    argv: string[];
+    displayArgv?: string[];
+    tool: string;
+    runtime?: RuntimeOverrideOptions;
+    context?: {
+        homeDir?: string;
+        state?: StateManager;
+    };
+    openSpec?: Partial<Pick<OpenSpec, "execution" | "shellSpec">>;
+}): {
+    factory: ReturnType<typeof selectExecutionEnv>;
+    openSpec: OpenSpec;
+    detach: boolean;
+    state: StateManager;
+};
+/** Raised when a requested runner capability is not offered by the resolved execution env. */
+export declare class UnsupportedRuntimeCapabilityError extends Error {
+    constructor(message: string);
+}
+export interface LoadedRuntimeConfig extends ResolvedConfig {
+    /** Raw merged runtime scope preserved for re-parsing when overrides change the type. */
+    rawScope: Record<string, unknown>;
+}
+export declare function applyRuntimeOverrides(config: ResolvedConfig | LoadedRuntimeConfig, overrides: RuntimeOverrideOptions | undefined, cwd?: string): ResolvedConfig;

package/dist/agent-harness-tools/run-logs.d.ts

@@ -0,0 +1,17 @@
+export interface ResolveRunLogDirOptions {
+    planPath: string;
+    runner: string;
+    homeDir: string;
+}
+export interface RunLogFileSystem {
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    realpath?(path: string): Promise<string>;
+}
+export declare function resolveRunLogDir(options: ResolveRunLogDirOptions): string;
+export declare function ensureSafeRunLogDir(options: ResolveRunLogDirOptions & {
+    fs?: RunLogFileSystem;
+}): Promise<string>;
+export declare function slugifyPlanPath(planPath: string): string;
+export declare function makeRunLogFileName(role: string, date?: Date): string;

package/dist/agent-harness-tools/run-poe-command.d.ts

@@ -0,0 +1,33 @@
+import type { StateManager } from "../poe-code-config/index.js";
+import type { DownloadResult, ExecutionEnvFactory, OpenSpec } from "./execution-env.js";
+export declare function runPoeCommand(opts: {
+    factory: ExecutionEnvFactory;
+    openSpec: OpenSpec;
+    detach: boolean;
+    state: StateManager;
+    signal?: AbortSignal;
+}): Promise<{
+    kind: "sync";
+    exitCode: number;
+    download: DownloadResult;
+    stdout?: string;
+    stderr?: string;
+} | {
+    kind: "detached";
+    jobId: string;
+    envId: string;
+}>;
+export interface PoeCommandSession {
+    run(openSpec: OpenSpec, signal?: AbortSignal): Promise<{
+        kind: "sync";
+        exitCode: number;
+        download: DownloadResult;
+        stdout?: string;
+        stderr?: string;
+    }>;
+    close(): Promise<void>;
+}
+export declare function createPoeCommandSession(opts: {
+    factory: ExecutionEnvFactory;
+    state: StateManager;
+}): PoeCommandSession;

package/dist/agent-harness-tools/runner.d.ts

@@ -0,0 +1,33 @@
+import { type RunAgentFn } from "./hooks.js";
+export interface WorkflowFileStat {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    mtimeMs: number;
+}
+export interface WorkflowFileSystem {
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    stat(path: string): Promise<WorkflowFileStat>;
+}
+export interface DocumentWorkflowOptions {
+    cwd: string;
+    homeDir: string;
+    docPath: string;
+    fs: WorkflowFileSystem;
+    runAgent: RunAgentFn;
+    readConfig: (content: string) => {
+        frontmatter: any;
+        body: string;
+    } | Promise<{
+        frontmatter: any;
+        body: string;
+    }>;
+    signal?: AbortSignal;
+    onIterationStart?: (iteration: number) => void | Promise<void>;
+    onIterationEnd?: (iteration: number, result: IterationResult) => void | Promise<void>;
+}
+export type IterationResult = "completed" | "nothing_to_run" | "failed";
+export declare function runDocumentWorkflow(options: DocumentWorkflowOptions): Promise<void>;

package/dist/agent-harness-tools/select-agent.d.ts

@@ -0,0 +1,18 @@
+type Select = typeof import("../toolcraft-design/index.js").select;
+type IsCancel = typeof import("../toolcraft-design/index.js").isCancel;
+export interface ResolveLoopAgentInput {
+    providedAgent?: string;
+    configuredDefaultAgent?: string | null;
+    frontmatterAgent?: string | string[];
+    assumeYes: boolean;
+    fallbackAgent: string;
+    message: string;
+    select: Select;
+    isCancel: IsCancel;
+}
+export declare function resolveLoopAgent(input: ResolveLoopAgentInput): Promise<{
+    agent: string;
+} | {
+    cancelled: true;
+}>;
+export {};

package/dist/agent-harness-tools/sequence.d.ts

@@ -0,0 +1,7 @@
+import { type DocumentWorkflowOptions } from "./runner.js";
+export interface DocumentWorkflowSequenceOptions extends Omit<DocumentWorkflowOptions, "docPath"> {
+    docPaths: string[];
+    stopOnFailure?: boolean;
+    onSequenceProgress?: (index: number, total: number, docPath: string) => void;
+}
+export declare function runDocumentWorkflowSequence(options: DocumentWorkflowSequenceOptions): Promise<void>;

package/dist/agent-harness-tools/skill-config.d.ts

@@ -0,0 +1 @@
+export declare function skillPlanConfigSection(subcommand: string): string;

package/dist/agent-harness-tools/stage.d.ts

@@ -0,0 +1,22 @@
+import { type RunAgentFn, type RunAgentHooks, type WorkflowMode } from "./hooks.js";
+import { type WorkflowParticipant } from "./participant.js";
+export interface WorkflowStage {
+    id: string;
+    participant: string;
+    prompt?: string;
+    mode?: WorkflowMode;
+    skills?: string[];
+    hooks?: RunAgentHooks;
+    onFailure?: "stop" | "continue";
+}
+export interface StageContext {
+    cwd: string;
+    participants: Record<string, WorkflowParticipant>;
+    runAgent: RunAgentFn;
+    signal?: AbortSignal;
+    iteration: number;
+}
+export declare function runWorkflowStage(stage: WorkflowStage, context: StageContext): Promise<{
+    success: boolean;
+    error?: Error;
+}>;

package/dist/agent-harness-tools/workspace-transfer.d.ts

@@ -0,0 +1,3 @@
+export { downloadWorkspace, uploadWorkspace } from "../process-runner/index.js";
+export type { WorkspaceDownloadOptions, WorkspaceTransferDirent, WorkspaceTransferEnv, WorkspaceTransferFileSystem, WorkspaceTransferOptions, WorkspaceTransferRunnerOptions, WorkspaceTransferStats } from "../process-runner/index.js";
+export type { DownloadResult, UploadResult } from "./execution-env.js";

package/dist/agent-spawn/acp/middleware.d.ts

@@ -0,0 +1,38 @@
+import type { SpawnMode, SpawnUsage } from "../types.js";
+import type { AcpEvent } from "./types.js";
+export interface SessionToolCall {
+    id?: string;
+    kind?: string;
+    title?: string;
+    input?: unknown;
+    path?: string;
+}
+export interface SessionResult {
+    output: string;
+    messages: string[];
+    toolCalls: SessionToolCall[];
+}
+export interface SpawnContext {
+    sessionId: string;
+    agent: string;
+    logPath?: string;
+    logDir?: string;
+    logFileName?: string;
+    logContent?: boolean;
+    events: AcpEvent[];
+    usage: SpawnUsage;
+    eventStream?: AsyncIterable<AcpEvent>;
+    sessionResult?: SessionResult;
+    threadId?: string;
+    prompt?: string;
+    model?: string;
+    mode?: SpawnMode;
+    cwd?: string;
+    startedAt?: Date;
+    logFile?: string;
+    /** Reason the spawn log could not be written, when logging failed. */
+    logError?: string;
+    metadata?: Record<string, unknown>;
+}
+export type AcpMiddleware = (ctx: SpawnContext, next: () => Promise<void>) => Promise<void>;
+export declare function applyMiddlewares(middlewares: AcpMiddleware[], ctx: SpawnContext): Promise<void>;

package/dist/agent-spawn/acp/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * ACP-related types used by `agent-spawn`.
+ *
+ * We intentionally keep these types *structurally compatible* with the official ACP schema (but do not
+ * depend on ACP packages) so we can move closer to full ACP compliance later without rewriting adapters.
+ *
+ * This file contains two related shapes:
+ * - `SessionUpdate` types (`tool_call`, `tool_call_update`, etc.) which mirror the official ACP schema.
+ * - `AcpEvent` (our internal rendering stream), which is *not* full ACP and uses a simplified vocabulary
+ *   for clearer semantics in the UI.
+ *
+ * Note: The official ACP docs/spec live at:
+ * - https://agentclientprotocol.com/
+ * - https://github.com/agentclientprotocol/agent-client-protocol
+ *
+ * TODO: Consider full ACP alignment (JSON-RPC, official discriminators, `execute` tool kind) if we need
+ * interop with Zed/JetBrains/other ACP clients.
+ */
+export type ToolKind = "read" | "edit" | "delete" | "move" | "search" | "execute" | "think" | "fetch" | "switch_mode" | "other";
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export type ToolCallStatus = "pending" | "in_progress" | "completed" | "failed" | "cancelled";
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export interface ContentChunk {
+    type: "text";
+    text: string;
+}
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export interface AgentMessageChunk {
+    sessionUpdate: "agent_message_chunk";
+    content: ContentChunk;
+}
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export interface AgentThoughtChunk {
+    sessionUpdate: "agent_thought_chunk";
+    content: ContentChunk;
+}
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export interface ToolCall {
+    sessionUpdate: "tool_call";
+    toolCallId: string;
+    title: string;
+    content?: ToolCallContent[];
+    kind?: ToolKind;
+    locations?: ToolCallLocation[];
+    status?: ToolCallStatus;
+    rawInput?: unknown;
+    rawOutput?: unknown;
+    _meta?: Record<string, unknown>;
+}
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export type ToolCallContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    mimeType: string;
+    data: string;
+};
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export interface ToolCallLocation {
+    path: string;
+    lineNumber?: number | null;
+    _meta?: Record<string, unknown>;
+}
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export interface ToolCallUpdate {
+    sessionUpdate: "tool_call_update";
+    toolCallId: string;
+    kind?: ToolKind;
+    status?: ToolCallStatus | null;
+    rawOutput?: unknown;
+    rawInput?: unknown;
+    content?: ToolCallContent[] | null;
+    locations?: ToolCallLocation[] | null;
+    title?: string | null;
+    _meta?: Record<string, unknown>;
+}
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export interface UsageUpdate {
+    sessionUpdate: "usage_update";
+    used: number;
+    size: number;
+    cost?: {
+        amount: number;
+        currency: string;
+    };
+    _meta?: Record<string, unknown>;
+}
+/** ACP-compatible type - @see https://agentclientprotocol.com/ - no package dependency, structural compatibility only */
+export type SessionUpdate = AgentMessageChunk | AgentThoughtChunk | ToolCall | ToolCallUpdate | UsageUpdate;
+export interface SessionStartEvent {
+    event: "session_start";
+    threadId?: string;
+    _meta?: Record<string, unknown>;
+}
+export interface AgentMessageEvent {
+    event: "agent_message";
+    text: string;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Internal event representing the start of a tool invocation.
+ *
+ * ACP models tools via `tool_call` and subsequent `tool_call_update` messages. We instead emit a clearer
+ * pair of events (`tool_start` / `tool_complete`) because our renderer wants an explicit lifecycle with
+ * unambiguous "start" vs "done" semantics.
+ *
+ * @see https://agentclientprotocol.com/protocol/tool-calls - we use simplified internal format
+ */
+export interface ToolStartEvent {
+    event: "tool_start";
+    /**
+     * Tool kind for rendering/logging.
+     *
+     * Note: our internal stream uses `"exec"` instead of ACP `"execute"` for brevity. This is intentionally
+     * not typed as `ToolKind` to avoid implying full ACP compliance.
+     */
+    kind: string;
+    title: string;
+    id?: string;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Internal event representing completion of a tool invocation.
+ *
+ * This corresponds conceptually to an ACP `tool_call_update` whose status is terminal (`completed`/`failed`),
+ * but is intentionally simpler for UI consumption.
+ */
+export interface ToolCompleteEvent {
+    event: "tool_complete";
+    kind: string;
+    path: string;
+    id?: string;
+    _meta?: Record<string, unknown>;
+}
+export interface ReasoningEvent {
+    event: "reasoning";
+    text: string;
+    _meta?: Record<string, unknown>;
+}
+export interface UsageEvent {
+    event: "usage";
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens?: number;
+    costUsd?: number;
+    costSource?: "reported" | "estimated";
+    _meta?: Record<string, unknown>;
+}
+export interface ErrorEvent {
+    event: "error";
+    message: string;
+    stack?: string;
+    _meta?: Record<string, unknown>;
+}
+/** Emitted when auto mode rejects an agent permission request, so the rejection is visible as the cause. */
+export interface PermissionRejectedEvent {
+    event: "permission_rejected";
+    title: string;
+    _meta?: Record<string, unknown>;
+}
+export interface SpawnResultEvent {
+    event: "spawn_result";
+    exitCode: number;
+    threadId?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cachedTokens?: number;
+        costUsd?: number;
+        costSource?: "reported" | "estimated";
+    };
+    protocolVersion?: number;
+    _meta?: Record<string, unknown>;
+}
+export type KnownAcpEvent = SessionStartEvent | AgentMessageEvent | ToolStartEvent | ToolCompleteEvent | ReasoningEvent | UsageEvent | ErrorEvent | PermissionRejectedEvent | SpawnResultEvent;
+export type UnknownAcpEvent = {
+    event: string;
+} & Record<string, unknown>;
+export type AcpEvent = KnownAcpEvent | UnknownAcpEvent;

package/dist/agent-spawn/adapters/claude.d.ts

@@ -0,0 +1,3 @@
+import type { AcpEvent } from "../acp/types.js";
+export declare const TOOL_KIND_MAP: Record<string, string>;
+export declare function adaptClaude(lines: AsyncIterable<string>): AsyncGenerator<AcpEvent>;

package/dist/agent-spawn/adapters/codex.d.ts

@@ -0,0 +1,2 @@
+import type { AcpEvent } from "../acp/types.js";
+export declare function adaptCodex(lines: AsyncIterable<string>): AsyncGenerator<AcpEvent>;

package/dist/agent-spawn/adapters/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { AcpEvent } from "../acp/types.js";
+export declare function adaptCursor(lines: AsyncIterable<string>): AsyncGenerator<AcpEvent>;

package/dist/agent-spawn/adapters/index.d.ts

@@ -0,0 +1,12 @@
+import type { AcpEvent, SessionUpdate } from "../acp/types.js";
+export { adaptCodex } from "./codex.js";
+export { adaptClaude } from "./claude.js";
+export { adaptKimi } from "./kimi.js";
+export { adaptNative } from "./native.js";
+export { adaptOpenCode } from "./opencode.js";
+export { adaptPi } from "./pi.js";
+export { adaptCursor } from "./cursor.js";
+export type AdapterType = "codex" | "claude" | "cursor" | "kimi" | "native" | "opencode" | "pi";
+export type AdapterOutput = AcpEvent | SessionUpdate;
+export type Adapter = (lines: AsyncIterable<string>) => AsyncGenerator<AdapterOutput>;
+export declare function getAdapter(type: AdapterType): Adapter;

package/dist/agent-spawn/adapters/kimi.d.ts

@@ -0,0 +1,2 @@
+import type { AcpEvent } from "../acp/types.js";
+export declare function adaptKimi(lines: AsyncIterable<string>): AsyncGenerator<AcpEvent>;

package/dist/agent-spawn/adapters/native.d.ts

@@ -0,0 +1,5 @@
+type AcpEvent = {
+    event: string;
+} & Record<string, unknown>;
+export declare function adaptNative(lines: AsyncIterable<string>): AsyncGenerator<AcpEvent>;
+export {};

package/dist/agent-spawn/adapters/opencode.d.ts

@@ -0,0 +1,2 @@
+import type { AcpEvent } from "../acp/types.js";
+export declare function adaptOpenCode(lines: AsyncIterable<string>): AsyncGenerator<AcpEvent>;

package/dist/agent-spawn/adapters/pi.d.ts

@@ -0,0 +1,2 @@
+import type { AcpEvent } from "../acp/types.js";
+export declare function adaptPi(lines: AsyncIterable<string>): AsyncGenerator<AcpEvent>;

package/dist/agent-spawn/environment.d.ts

@@ -0,0 +1,2 @@
+export type SpawnEnvironment = Record<string, string | undefined>;
+export declare function mergeSpawnEnvironment(...sources: Array<SpawnEnvironment | NodeJS.ProcessEnv | undefined>): Record<string, string>;

package/dist/agent-spawn/parallel.d.ts

@@ -0,0 +1,30 @@
+import type { SpawnHandle } from "./retry.js";
+export type SpawnParallelTuple<TService, TOptions> = readonly [
+    service: TService,
+    options: TOptions
+];
+export type SpawnParallelThunk<TResult extends {
+    exitCode: number;
+}> = (signal?: AbortSignal) => SpawnHandle<TResult>;
+export type SpawnParallelCall<TService, TOptions, TResult extends {
+    exitCode: number;
+}> = SpawnParallelTuple<TService, TOptions> | SpawnParallelThunk<TResult>;
+export type SpawnParallelOptions = {
+    check?: boolean;
+    maxConcurrent?: number;
+    failFast?: boolean;
+    signal?: AbortSignal;
+};
+export declare class SpawnParallelError<TResult extends {
+    exitCode: number;
+}> extends Error {
+    readonly index: number;
+    readonly result: TResult;
+    readonly results: Array<TResult | undefined>;
+    constructor(index: number, result: TResult, results: Array<TResult | undefined>);
+}
+export declare function createSpawnParallel<TService, TOptions extends {
+    signal?: AbortSignal;
+}, TResult extends {
+    exitCode: number;
+}>(spawnOnce: (service: TService, options: TOptions) => SpawnHandle<TResult>): (calls: Array<SpawnParallelCall<TService, TOptions, TResult>>, options?: SpawnParallelOptions) => Promise<TResult[]>;

package/dist/agent-spawn/retry.d.ts

@@ -0,0 +1,26 @@
+import type { AcpEvent } from "./acp/types.js";
+export type SpawnRetryOptions<TResult extends {
+    exitCode: number;
+}> = {
+    maxAttempts: number;
+    backoffMs: number;
+    isRetryable?: (result: TResult) => boolean;
+};
+export type SpawnHandle<TResult> = {
+    events: AsyncIterable<AcpEvent>;
+    result: Promise<TResult>;
+};
+export type SpawnRetryFunction<TOptions extends {
+    signal?: AbortSignal;
+}, TResult extends {
+    exitCode: number;
+}> = (service: string, options: TOptions, retryOptions: SpawnRetryOptions<TResult>) => SpawnHandle<TResult>;
+export declare function createSpawnRetry<TOptions extends {
+    signal?: AbortSignal;
+}, TResult extends {
+    exitCode: number;
+}>(spawnOnce: (service: string, options: TOptions) => SpawnHandle<TResult>): SpawnRetryFunction<TOptions, TResult>;
+export declare function defaultIsRetryable(result: {
+    exitCode: number;
+}): boolean;
+export declare function calculateBackoffMs(baseBackoffMs: number, completedAttempt: number): number;