@poe-platform/safe-js 0.1.0

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

@@ -0,0 +1,272 @@
+import type { AdapterType } from "./adapters/index.js";
+import type { RuntimeOverrideOptions } from "../agent-harness-tools/index.js";
+import type { StateManager } from "../poe-code-config/index.js";
+import type { AcpMiddleware } from "./acp/middleware.js";
+import type { SpawnEnvironment } from "./environment.js";
+export declare const SPAWN_MODES: readonly ["yolo", "auto", "edit", "read"];
+export type SpawnMode = (typeof SPAWN_MODES)[number];
+/**
+ * The single source of truth for the permission mode used when a caller does not
+ * ask for one. `auto` uses the provider's unattended safe-action policy.
+ * Providers without an auto mode reject the spawn instead of silently selecting
+ * a more permissive mode. `yolo` must always be requested explicitly.
+ */
+export declare const DEFAULT_SPAWN_MODE: SpawnMode;
+export type SpawnModeConfig = string[] | {
+    args?: string[];
+    env?: Record<string, string>;
+};
+/**
+ * `auto` is optional: it maps to the agent's native ask-style approval mode and
+ * must be omitted when the agent has no approval channel in headless runs.
+ */
+export type SpawnModesConfig = Record<Exclude<SpawnMode, "auto">, SpawnModeConfig> & {
+    auto?: SpawnModeConfig;
+};
+export declare function resolveModeConfig(modeConfig: SpawnModeConfig): {
+    args: string[];
+    env?: Record<string, string>;
+};
+export declare function resolveAgentModeConfig(config: Pick<CliSpawnConfig, "agentId" | "modes">, mode: SpawnMode | undefined): {
+    args: string[];
+    env?: Record<string, string>;
+};
+export interface McpSpawnServer {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /**
+     * Whether Codex should automatically approve tools exposed by this explicitly configured server.
+     * Defaults to true so headless read/edit spawns can use caller-trusted MCP tools.
+     */
+    autoApprove?: boolean;
+    /**
+     * Maximum time in seconds the agent should wait for a single tool call
+     * to this MCP server before timing out. Omit to use the agent's default.
+     */
+    timeout?: number;
+}
+export type McpSpawnConfig = Record<string, McpSpawnServer>;
+export interface McpFileSpec {
+    relativePath: string;
+    content: (servers: McpSpawnConfig) => Record<string, unknown>;
+}
+export type OtelSpan = {
+    setAttribute(key: string, value: unknown): void;
+    addEvent(name: string, attrs: Record<string, unknown>): void;
+    end(): void;
+};
+export interface OtelSink {
+    startSpan(name: string, attrs: Record<string, unknown>): OtelSpan;
+    recordException(span: ReturnType<OtelSink["startSpan"]>, error: unknown): void;
+}
+export interface HookBridgeOptions {
+    from: string;
+    strategy?: "auto" | "symlink" | "transform";
+    scope?: "project" | "user" | "merged";
+}
+export interface SpawnOptions {
+    prompt: string;
+    cwd?: string;
+    model?: string;
+    mode?: SpawnMode;
+    args?: string[];
+    mcpServers?: McpSpawnConfig;
+    /** Skill references to bridge into the spawned agent for this run. */
+    skills?: string[];
+    /** Hooks to bridge from another agent configuration for this run. */
+    hooks?: HookBridgeOptions;
+    /** Resume a prior provider thread/session before sending the prompt. */
+    resumeThreadId?: string;
+    useStdin?: boolean;
+    interactive?: boolean;
+    signal?: AbortSignal;
+    otelSink?: OtelSink;
+    /** Capture native OTLP telemetry emitted by the spawned agent. */
+    captureOtel?: boolean;
+    /** Include prompt and tool content in native OTLP telemetry. */
+    captureOtelContent?: boolean;
+    /** Additional environment passed to the spawned agent. */
+    env?: SpawnEnvironment;
+    middlewares?: AcpMiddleware[];
+    tee?: {
+        stdout?: {
+            write(chunk: string): void;
+        };
+        stderr?: {
+            write(chunk: string): void;
+        };
+    };
+    /**
+     * Kill the spawned process after this many milliseconds of inactivity (no stdout data).
+     * Resets on every chunk of stdout/stderr received. Disabled when undefined.
+     */
+    activityTimeoutMs?: number;
+    /**
+     * Full path for the spawn log file. When set, stdout (and stderr for CLI spawns)
+     * are appended to this file, and the absolute path is returned in `SpawnResult.logFile`.
+     * Takes precedence over `logDir` + `logFileName`.
+     */
+    logPath?: string;
+    /**
+     * Directory for the spawn log file. When set together with `logFileName`, stdout
+     * (and stderr for CLI spawns) are appended to `<logDir>/<logFileName>`, and the
+     * absolute path is returned in `SpawnResult.logFile`.
+     */
+    logDir?: string;
+    /** Overrides the auto-generated log filename. Must be used together with `logDir`. */
+    logFileName?: string;
+    /** Per-invocation runtime/runner config overrides. */
+    runtime?: RuntimeOverrideOptions["runtime"];
+    /** Docker image override for docker runtime. */
+    runtimeImage?: string;
+    /** Directory used to load runtime config/templates when different from cwd. */
+    runtimeConfigCwd?: string;
+    /** Run through a detached runtime job when the backend supports it. */
+    detach?: boolean;
+    /** Mount the local poe-code checkout into the runtime for development. */
+    mountPoeCode?: boolean;
+    /** Override runner workspace sync behavior. */
+    runnerSync?: RuntimeOverrideOptions["runnerSync"];
+}
+export interface SpawnUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens?: number;
+    costUsd?: number;
+}
+export interface SpawnResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs?: number;
+    threadId?: string;
+    usage?: SpawnUsage;
+    logFile?: string;
+    detached?: {
+        jobId: string;
+        envId: string;
+    };
+}
+export interface AutonomousResult {
+    summary?: string;
+    log?: string;
+    output?: string;
+    stdout?: string;
+    text?: string;
+    logFile?: string;
+    toolCalls?: unknown[];
+    sessionResult?: {
+        toolCalls?: unknown[];
+    };
+}
+export interface SpawnLogger {
+    dryRun(message: string): void;
+}
+export interface SpawnContext {
+    dryRun?: boolean;
+    logger?: SpawnLogger;
+    homeDir?: string;
+    state?: StateManager;
+}
+export interface StdinMode {
+    omitPrompt: boolean;
+    extraArgs: string[];
+    automaticFallback?: boolean;
+}
+export interface InteractiveSpawnConfig {
+    defaultArgs: string[];
+    defaultArgsPosition?: "beforePrompt" | "afterPrompt";
+    promptFlag?: string;
+}
+export interface CliSpawnConfig {
+    kind: "cli";
+    agentId: string;
+    adapter: AdapterType;
+    promptFlag?: string;
+    defaultArgs: string[];
+    defaultArgsPosition?: "beforePrompt" | "afterPrompt";
+    modes: SpawnModesConfig;
+    stdinMode?: StdinMode;
+    modelFlag?: string;
+    /**
+     * Controls whether the provider prefix is stripped from model IDs before passing to the CLI binary.
+     *
+     * When `true`: "anthropic/claude-opus-4.6" → "claude-opus-4.6", "openai/gpt-5.2" → "gpt-5.2"
+     * When `false`: "anthropic/claude-opus-4.6" stays as-is, "openai/gpt-5.2" stays as-is
+     *
+     * Most CLI binaries only accept bare model IDs (e.g. `claude --model claude-opus-4.6`),
+     * so they need `true`. OpenCode routes through poe and needs the full provider path, so it uses `false`.
+     */
+    modelStripProviderPrefix: boolean;
+    /** Transform model ID before passing to CLI. Runs after provider prefix stripping (if enabled). */
+    modelTransform?: (model: string) => string;
+    /**
+     * Transforms MCP server config into CLI args for this agent.
+     * Presence of this function declares spawn-time MCP support.
+     */
+    mcpArgs?: (servers: McpSpawnConfig) => string[];
+    /**
+     * Transforms MCP server config into env vars for this agent.
+     * Use instead of `mcpArgs` when the agent reads MCP config from the environment.
+     */
+    mcpEnv?: (servers: McpSpawnConfig) => Record<string, string>;
+    mcpFile?: McpFileSpec;
+    /**
+     * Controls where serialized MCP args are inserted relative to the command.
+     *
+     * - "beforeCommand": before the prompt/subcommand section (e.g. `codex -c ... exec "prompt"`)
+     * - "beforePrompt": after `defaultArgs` but before the prompt/model section
+     * - "afterCommand": after `defaultArgs` (default)
+     */
+    mcpArgsPosition?: "beforeCommand" | "beforePrompt" | "afterCommand";
+    /**
+     * @deprecated Prefer `mcpArgsPosition`.
+     * When true, MCP args are placed before the subcommand (e.g. `codex -c ... exec "prompt"`).
+     * When false/undefined, they are placed after defaultArgs (e.g. `claude -p "prompt" --mcp-servers ...`).
+     */
+    mcpArgsBeforeCommand?: boolean;
+    interactive?: InteractiveSpawnConfig;
+    resume?: ResumeSpec;
+}
+export interface ResumeSpec {
+    /** Args injected into the live spawn for non-interactive resume. */
+    args: (threadId: string, cwd: string) => string[];
+    /** Position of `args` relative to the prompt token. Default `afterPrompt`. */
+    position?: "beforePrompt" | "afterPrompt";
+    /**
+     * Some CLIs implement resume as a subcommand under the normal prompt command
+     * and require command options before the resume token.
+     */
+    commandOptionsPosition?: "beforeResume";
+    /**
+     * Optional override for the printed copy-paste resume hint (e.g. an interactive
+     * shell command). When omitted, the hint composes binaryName + `args`.
+     */
+    hintArgs?: (threadId: string, cwd: string) => string[];
+}
+export interface FileSpawnConfig {
+    kind: "file";
+    agentId: string;
+    launchCommand?: string;
+    launchArgs?: string[];
+}
+export interface AcpSpawnConfig {
+    kind: "acp";
+    agentId: string;
+    /** Args passed to the agent binary to start its ACP server (e.g. ["acp"]). */
+    acpArgs: string[] | ((options: {
+        model?: string;
+        mode?: SpawnMode;
+        mcpServers?: McpSpawnConfig;
+    }) => string[]);
+    /** Environment variables required by the ACP server process. */
+    env?: Record<string, string>;
+    /** Whether to skip the ACP authenticate step (workaround for servers that advertise but don't implement auth). */
+    skipAuth?: boolean;
+    /** Whether MCP servers may be forwarded through ACP sessions. Defaults to true. */
+    supportsMcpServers?: boolean;
+    /** MCP server env serializer, same as CliSpawnConfig. */
+    mcpEnv?: (servers: McpSpawnConfig) => Record<string, string>;
+}
+export type SpawnConfig = CliSpawnConfig | FileSpawnConfig | AcpSpawnConfig;

package/dist/auth-store/create-secret-store.d.ts

@@ -0,0 +1,2 @@
+import type { CreateSecretStoreInput, CreateSecretStoreResult } from "./types.js";
+export declare function createSecretStore(input: CreateSecretStoreInput): CreateSecretStoreResult;

package/dist/auth-store/encrypted-file-store.d.ts

@@ -0,0 +1,47 @@
+import type { SecretStore } from "./types.js";
+export interface MachineIdentity {
+    hostname: string;
+    username: string;
+}
+export interface EncryptedFileStoreFileSystem {
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    writeFile(path: string, data: string | NodeJS.ArrayBufferView, options?: {
+        encoding?: BufferEncoding;
+        flag?: string;
+        mode?: number;
+    }): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void | string | undefined>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    lstat(path: string): Promise<{
+        isSymbolicLink(): boolean;
+    }>;
+    unlink(path: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+}
+export interface EncryptedFileStoreInput {
+    fs?: EncryptedFileStoreFileSystem;
+    filePath?: string;
+    salt: string;
+    defaultDirectory?: string;
+    defaultFileName?: string;
+    getMachineIdentity?: () => MachineIdentity | Promise<MachineIdentity>;
+    getHomeDirectory?: () => string;
+    getRandomBytes?: (size: number) => Buffer;
+}
+export declare class EncryptedFileStore implements SecretStore {
+    private readonly fs;
+    private readonly filePath;
+    private readonly symbolicLinkCheckStartPath;
+    private readonly salt;
+    private readonly getMachineIdentity;
+    private readonly getRandomBytes;
+    private keyPromise;
+    constructor(input: EncryptedFileStoreInput);
+    get(): Promise<string | null>;
+    set(value: string): Promise<void>;
+    delete(): Promise<void>;
+    private assertCredentialPathHasNoSymbolicLinks;
+    private getEncryptionKey;
+}

package/dist/auth-store/index.d.ts

@@ -0,0 +1,7 @@
+export { createSecretStore } from "./create-secret-store.js";
+export { EncryptedFileStore } from "./encrypted-file-store.js";
+export { KeychainStore } from "./keychain-store.js";
+export { key, MigratingSecretStore } from "./provider-store.js";
+export type { SecretStore, StoreBackend, CreateSecretStoreInput, CreateSecretStoreResult } from "./types.js";
+export type { MachineIdentity, EncryptedFileStoreInput, EncryptedFileStoreFileSystem } from "./encrypted-file-store.js";
+export type { KeychainStoreInput, KeychainCommandRunner, KeychainCommandResult, KeychainCommandOptions } from "./keychain-store.js";

package/dist/auth-store/keychain-store.d.ts

@@ -0,0 +1,25 @@
+import type { SecretStore } from "./types.js";
+export interface KeychainCommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface KeychainCommandOptions {
+    stdin?: string;
+}
+export type KeychainCommandRunner = (command: string, args: string[], options?: KeychainCommandOptions) => Promise<KeychainCommandResult>;
+export interface KeychainStoreInput {
+    runCommand?: KeychainCommandRunner;
+    service: string;
+    account: string;
+}
+export declare class KeychainStore implements SecretStore {
+    private readonly runCommand;
+    private readonly service;
+    private readonly account;
+    constructor(input: KeychainStoreInput);
+    get(): Promise<string | null>;
+    set(value: string): Promise<void>;
+    delete(): Promise<void>;
+    private executeSecurityCommand;
+}

package/dist/auth-store/provider-store.d.ts

@@ -0,0 +1,14 @@
+import type { SecretStore } from "./types.js";
+export declare function key(providerId: string): string;
+export declare class MigratingSecretStore implements SecretStore {
+    private readonly store;
+    private readonly legacyStore;
+    private pendingMutation;
+    constructor(store: SecretStore, legacyStore?: SecretStore | null);
+    get(options?: {
+        readOnly?: boolean;
+    }): Promise<string | null>;
+    set(value: string): Promise<void>;
+    delete(): Promise<void>;
+    private mutate;
+}

package/dist/auth-store/types.d.ts

@@ -0,0 +1,22 @@
+import type { EncryptedFileStoreInput } from "./encrypted-file-store.js";
+import type { KeychainStoreInput } from "./keychain-store.js";
+export interface SecretStore {
+    get(options?: {
+        readOnly?: boolean;
+    }): Promise<string | null>;
+    set(value: string): Promise<void>;
+    delete(): Promise<void>;
+}
+export type StoreBackend = "file" | "keychain";
+export interface CreateSecretStoreInput {
+    backend?: StoreBackend;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    backendEnvVar?: string;
+    fileStore?: EncryptedFileStoreInput;
+    keychainStore?: KeychainStoreInput;
+}
+export interface CreateSecretStoreResult {
+    store: SecretStore;
+    backend: StoreBackend;
+}

package/dist/config-mutations/execution/run-mutations.d.ts

@@ -0,0 +1,7 @@
+import type { Mutation, MutationContext, MutationResult, MutationOptions } from "../types.js";
+/**
+ * Execute an array of mutations in order.
+ *
+ * All dependencies must be injected - no defaults, no globals.
+ */
+export declare function runMutations(mutations: Mutation[], context: MutationContext, options?: MutationOptions): Promise<MutationResult>;

package/dist/config-mutations/fs-utils.d.ts

@@ -0,0 +1,18 @@
+import type { FileSystem } from "./types.js";
+/**
+ * Check if an error is a "file not found" (ENOENT) error.
+ */
+export declare function isNotFound(error: unknown): boolean;
+/**
+ * Read a file if it exists, returning null if not found.
+ */
+export declare function readFileIfExists(fs: FileSystem, target: string): Promise<string | null>;
+/**
+ * Check if a path exists (file or directory).
+ */
+export declare function pathExists(fs: FileSystem, target: string): Promise<boolean>;
+/**
+ * Create an ISO timestamp safe for use in filenames.
+ * Replaces colons and dots with dashes.
+ */
+export declare function createTimestamp(): string;

package/dist/config-mutations/index.d.ts

@@ -0,0 +1,8 @@
+export { configMutation } from "./mutations/config-mutation.js";
+export { fileMutation } from "./mutations/file-mutation.js";
+export { templateMutation } from "./mutations/template-mutation.js";
+export { runMutations } from "./execution/run-mutations.js";
+export { renderTemplate, type TemplateVariables } from "./template/render.js";
+export { isNotFound, readFileIfExists, pathExists, createTimestamp } from "./fs-utils.js";
+export type { ConfigObject, ConfigValue, Mutation, MutationContext, MutationResult, MutationObservers, MutationDetails, MutationOutcome, FileSystem, TemplateLoader, ConfigFormat, PathMapper } from "./types.js";
+export { isConfigObject } from "./types.js";

package/dist/config-mutations/mutations/config-mutation.d.ts

@@ -0,0 +1,47 @@
+import type { ConfigMergeMutation, ConfigPruneMutation, ConfigTransformMutation, ConfigObject, ValueResolver, MutationOptions } from "../types.js";
+export interface MergeOptions {
+    /** Target file path (must start with ~) */
+    target: ValueResolver<string>;
+    /** Value to merge into the config file */
+    value: ValueResolver<ConfigObject>;
+    /** Optional explicit format override */
+    format?: "json" | "toml" | "yaml";
+    /** Optional prune by prefix before merging (TOML) */
+    pruneByPrefix?: Record<string, string>;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+export interface PruneOptions {
+    /** Target file path (must start with ~) */
+    target: ValueResolver<string>;
+    /** Shape to prune from the config file */
+    shape: ValueResolver<ConfigObject>;
+    /** Optional explicit format override */
+    format?: "json" | "toml" | "yaml";
+    /** Optional guard - only prune if predicate returns true */
+    onlyIf?: (doc: ConfigObject, ctx: MutationOptions) => boolean;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+export interface TransformOptions {
+    /** Target file path (must start with ~) */
+    target: ValueResolver<string>;
+    /** Optional explicit format override */
+    format?: "json" | "toml" | "yaml";
+    /** Transform function - receives parsed content, returns transformed content */
+    transform: (content: ConfigObject, ctx: MutationOptions) => {
+        content: ConfigObject | null;
+        changed: boolean;
+    };
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+declare function merge(options: MergeOptions): ConfigMergeMutation;
+declare function prune(options: PruneOptions): ConfigPruneMutation;
+declare function transform(options: TransformOptions): ConfigTransformMutation;
+export declare const configMutation: {
+    merge: typeof merge;
+    prune: typeof prune;
+    transform: typeof transform;
+};
+export {};

package/dist/config-mutations/mutations/file-mutation.d.ts

@@ -0,0 +1,62 @@
+import type { EnsureDirectoryMutation, RemoveDirectoryMutation, RemoveFileMutation, ChmodMutation, BackupMutation, RestoreBackupMutation, ValueResolver } from "../types.js";
+export interface EnsureDirectoryOptions {
+    /** Directory path (must start with ~) */
+    path: ValueResolver<string>;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+export interface RemoveOptions {
+    /** Target file path (must start with ~) */
+    target: ValueResolver<string>;
+    /** Only remove if file is empty/whitespace */
+    whenEmpty?: boolean;
+    /** Only remove if content matches regex */
+    whenContentMatches?: RegExp;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+export interface RemoveDirectoryOptions {
+    /** Directory path (must start with ~) */
+    path: ValueResolver<string>;
+    /** Remove directory even when not empty */
+    force?: boolean;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+export interface ChmodOptions {
+    /** Target file path (must start with ~) */
+    target: ValueResolver<string>;
+    /** File permission mode (e.g., 0o755) */
+    mode: number;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+export interface BackupOptions {
+    /** Target file path to backup (must start with ~) */
+    target: ValueResolver<string>;
+    /** Keep the first baseline only, including an originally missing target. */
+    once?: boolean;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+export interface RestoreBackupOptions {
+    /** Target file path whose latest generated backup should be restored. */
+    target: ValueResolver<string>;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+declare function ensureDirectory(options: EnsureDirectoryOptions): EnsureDirectoryMutation;
+declare function remove(options: RemoveOptions): RemoveFileMutation;
+declare function removeDirectory(options: RemoveDirectoryOptions): RemoveDirectoryMutation;
+declare function chmod(options: ChmodOptions): ChmodMutation;
+declare function backup(options: BackupOptions): BackupMutation;
+declare function restoreBackup(options: RestoreBackupOptions): RestoreBackupMutation;
+export declare const fileMutation: {
+    ensureDirectory: typeof ensureDirectory;
+    remove: typeof remove;
+    removeDirectory: typeof removeDirectory;
+    chmod: typeof chmod;
+    backup: typeof backup;
+    restoreBackup: typeof restoreBackup;
+};
+export {};

package/dist/config-mutations/mutations/template-mutation.d.ts

@@ -0,0 +1,40 @@
+import type { TemplateWriteMutation, TemplateMergeTomlMutation, TemplateMergeJsonMutation, ConfigObject, ValueResolver } from "../types.js";
+export interface WriteOptions {
+    /** Target file path (must start with ~) */
+    target: ValueResolver<string>;
+    /** Template ID to load via template loader */
+    templateId: string;
+    /** Context to pass to renderTemplate() */
+    context?: ValueResolver<ConfigObject>;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+export interface MergeTomlOptions {
+    /** Target TOML file path (must start with ~) */
+    target: ValueResolver<string>;
+    /** Template ID to load via template loader */
+    templateId: string;
+    /** Context to pass to renderTemplate() */
+    context?: ValueResolver<ConfigObject>;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+export interface MergeJsonOptions {
+    /** Target JSON file path (must start with ~) */
+    target: ValueResolver<string>;
+    /** Template ID to load via template loader */
+    templateId: string;
+    /** Context to pass to renderTemplate() */
+    context?: ValueResolver<ConfigObject>;
+    /** Optional human-readable label for logging */
+    label?: string;
+}
+declare function write(options: WriteOptions): TemplateWriteMutation;
+declare function mergeToml(options: MergeTomlOptions): TemplateMergeTomlMutation;
+declare function mergeJson(options: MergeJsonOptions): TemplateMergeJsonMutation;
+export declare const templateMutation: {
+    write: typeof write;
+    mergeToml: typeof mergeToml;
+    mergeJson: typeof mergeJson;
+};
+export {};

package/dist/config-mutations/template/render.d.ts

@@ -0,0 +1,6 @@
+export type TemplateVariables = Record<string, string | number | boolean | string[]>;
+/**
+ * Render a mustache template with the given variables.
+ * HTML escaping is disabled.
+ */
+export declare function renderTemplate(template: string, variables: TemplateVariables): string;