@agentex/agent 0.0.24 → 0.0.26

package/src/providers/process/execute.ts

@@ -0,0 +1,148 @@
+import type { ExecutionContext, ExecutionResult } from "../../types.js";
+import { ensureCommandResolvable } from "../../utils/binary.js";
+import { buildEnv, ensurePathInEnv } from "../../utils/env.js";
+import { runChildProcess, deriveErrorCode } from "../../utils/process.js";
+import { resolveInstructions } from "../../utils/instructions.js";
+import { prepareWorkspace } from "../../utils/workspace.js";
+import type { PreparedWorkspace } from "../../utils/workspace.js";
+import { uuidv7 } from "../../utils/uuid.js";
+
+export async function executeProcessProvider(ctx: ExecutionContext): Promise<ExecutionResult> {
+  const runId = ctx.runId ?? uuidv7();
+  let cwd = ctx.cwd ?? process.cwd();
+  const config = ctx.config ?? {};
+  const startedAt = new Date().toISOString();
+  const startMs = Date.now();
+  const command = config.command;
+
+  ctx.onLifecycle?.({ phase: "preparing", step: "binary" });
+  if (!command) {
+    const errorMessage = 'Process provider requires config.command to be set.';
+    ctx.onLifecycle?.({ phase: "error", message: errorMessage });
+    return {
+      runId,
+      exitCode: null,
+      signal: null,
+      status: "failed" as const,
+      startedAt,
+      completedAt: new Date().toISOString(),
+      durationMs: Date.now() - startMs,
+      errorMessage,
+      errorCode: "binary_not_found",
+      costUsd: null,
+      model: null,
+      summary: null,
+      sessionParams: null,
+      sessionDisplayId: null,
+      clearSession: false,
+      billingType: null,
+    };
+  }
+
+  let resolvedBinary;
+  try {
+    resolvedBinary = await ensureCommandResolvable(command);
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : "Command not found";
+    ctx.onLifecycle?.({ phase: "error", message: errorMessage });
+    return {
+      runId,
+      exitCode: null,
+      signal: null,
+      status: "failed" as const,
+      startedAt,
+      completedAt: new Date().toISOString(),
+      durationMs: Date.now() - startMs,
+      errorMessage,
+      errorCode: "binary_not_found",
+      costUsd: null,
+      model: null,
+      summary: null,
+      sessionParams: null,
+      sessionDisplayId: null,
+      clearSession: false,
+      billingType: null,
+    };
+  }
+
+  // Workspace isolation
+  let workspace: PreparedWorkspace | undefined;
+  if (config.workspace) {
+    ctx.onLifecycle?.({ phase: "preparing", step: "workspace" });
+    workspace = await prepareWorkspace(cwd, config.workspace);
+    cwd = workspace.cwd;
+  }
+
+  const env = buildEnv(ctx.env);
+  ensurePathInEnv(env);
+
+  // Resolve instructions
+  ctx.onLifecycle?.({ phase: "preparing", step: "instructions" });
+  const instructions = await resolveInstructions(config.instructionsFile);
+  const fullPrompt = instructions ? `${instructions}\n\n${ctx.prompt}` : ctx.prompt;
+
+  ctx.onLifecycle?.({ phase: "spawning" });
+  const proc = await runChildProcess({
+    runId,
+    command: resolvedBinary.bin,
+    args: [...resolvedBinary.prefixArgs, ...(config.extraArgs ?? [])],
+    cwd,
+    env,
+    stdin: fullPrompt,
+    timeoutSec: config.timeoutSec,
+    graceSec: config.graceSec,
+    onStart: (pid) => {
+      ctx.onLifecycle?.({ phase: "running", pid });
+      ctx.onStart?.(pid);
+    },
+    signal: ctx.signal,
+    onOutput: ctx.onOutput ? async (stream, chunk) => {
+      try { await ctx.onOutput!(stream, chunk); } catch { /* swallow */ }
+    } : undefined,
+  });
+
+  const errorCode = deriveErrorCode(proc);
+  const errorMessage = (() => {
+    if (proc.timedOut) return `Timed out after ${config.timeoutSec ?? 0}s`;
+    if ((proc.exitCode ?? 0) !== 0) {
+      const stderrLine = proc.stderr.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
+      return stderrLine ?? `Process exited with code ${proc.exitCode ?? -1}`;
+    }
+    return null;
+  })();
+
+  const completedAt = new Date().toISOString();
+  const status = proc.aborted ? "aborted" as const
+    : proc.timedOut ? "timeout" as const
+    : (errorCode || errorMessage) ? "failed" as const
+    : "completed" as const;
+
+  if (status === "completed") {
+    ctx.onLifecycle?.({ phase: "completed" });
+  } else if (status === "aborted") {
+    ctx.onLifecycle?.({ phase: "cancelled" });
+  } else {
+    ctx.onLifecycle?.({ phase: "error", message: errorMessage ?? "Unknown error" });
+  }
+
+  return {
+    runId,
+    exitCode: proc.exitCode,
+    signal: proc.signal ?? null,
+    status,
+    startedAt,
+    completedAt,
+    durationMs: new Date(completedAt).getTime() - startMs,
+    errorMessage,
+    errorCode,
+    costUsd: null,
+    model: null,
+    summary: proc.stdout.trim() || null,
+    sessionParams: null,
+    sessionDisplayId: null,
+    clearSession: false,
+    billingType: null,
+    raw: null,
+    workspace,
+  };
+}

package/src/providers/process/index.ts

@@ -0,0 +1,52 @@
+import type { AuthResolveContext, AuthReport, ProviderModule } from "../../types.js";
+import { ensureCommandResolvable } from "../../utils/binary.js";
+
+async function resolveProcessAuth(ctx?: AuthResolveContext): Promise<AuthReport> {
+  // Process is a generic runner — the "binary" is user-supplied via config.command.
+  // If a command is passed via ctx.command, probe it; otherwise report "unknown".
+  if (!ctx?.command) {
+    return {
+      providerType: "process",
+      binary: { installed: false, error: "No command specified (process provider requires config.command)" },
+      options: [],
+      source: "filesystem",
+    };
+  }
+  try {
+    const resolved = await ensureCommandResolvable(ctx.command);
+    return {
+      providerType: "process",
+      binary: { installed: true, resolvedPath: resolved.bin },
+      options: [],
+      source: "filesystem",
+    };
+  } catch (err) {
+    return {
+      providerType: "process",
+      binary: { installed: false, error: err instanceof Error ? err.message : String(err) },
+      options: [],
+      source: "filesystem",
+    };
+  }
+}
+
+export const processProvider: ProviderModule = {
+  type: "process",
+  capabilities: {
+    sessions: false,
+    modelDiscovery: false,
+    quotaProbing: false,
+    mcp: false,
+    skills: false,
+    instructions: true,
+    workspace: true,
+    planMode: false,
+    concurrentSend: false,
+    cancelQueuedMessage: false,
+    stopTask: false,
+    modes: false,
+  },
+  // execute.ts loads lazily on first use.
+  execute: async (ctx) => (await import("./execute.js")).executeProcessProvider(ctx),
+  resolveAuth: resolveProcessAuth,
+};

package/src/registry.ts

@@ -0,0 +1,40 @@
+import type { ProviderModule } from "./types.js";
+import { claudeProvider } from "./providers/claude/index.js";
+import { codexProvider } from "./providers/codex/index.js";
+import { openclawProvider } from "./providers/openclaw/index.js";
+import { processProvider } from "./providers/process/index.js";
+import { geminiProvider } from "./providers/gemini/index.js";
+import { cursorProvider } from "./providers/cursor/index.js";
+import { opencodeProvider } from "./providers/opencode/index.js";
+import { piProvider } from "./providers/pi/index.js";
+import { copilotProvider } from "./providers/copilot/index.js";
+
+const providers = new Map<string, ProviderModule>();
+
+// Pre-register built-in providers
+providers.set("claude", claudeProvider);
+providers.set("codex", codexProvider);
+providers.set("openclaw", openclawProvider);
+providers.set("process", processProvider);
+providers.set("gemini", geminiProvider);
+providers.set("cursor", cursorProvider);
+providers.set("opencode", opencodeProvider);
+providers.set("pi", piProvider);
+providers.set("copilot", copilotProvider);
+
+export function getProvider(type: string): ProviderModule {
+  const provider = providers.get(type);
+  if (!provider) {
+    const available = [...providers.keys()].join(", ");
+    throw new Error(`Unknown provider type "${type}". Available: ${available}`);
+  }
+  return provider;
+}
+
+export function listProviders(): string[] {
+  return [...providers.keys()];
+}
+
+export function registerProvider(provider: ProviderModule): void {
+  providers.set(provider.type, provider);
+}

package/src/sessions/index.ts

@@ -0,0 +1,8 @@
+export {
+  SESSION_RECORD_VERSION,
+  MalformedSessionRecordError,
+  createSessionRecord,
+  isSessionRecord,
+  assertSessionRecord,
+} from "./record.js";
+export type { CreateSessionRecordInput } from "./record.js";

package/src/sessions/record.ts

@@ -0,0 +1,108 @@
+import type { SessionRecord } from "../types.js";
+
+/**
+ * Current `SessionRecord.version`. Bumped only on a breaking shape change;
+ * `isSessionRecord` / `assertSessionRecord` validate against it so a host can
+ * detect a record written by an incompatible library version.
+ */
+export const SESSION_RECORD_VERSION = 1 as const;
+
+/**
+ * Thrown when a value that should be a `SessionRecord` is malformed. Branch on
+ * it; don't parse. Mirrors `MalformedProviderConfigError` — `path` names the
+ * offending field when known.
+ */
+export class MalformedSessionRecordError extends Error {
+  readonly path?: string;
+  constructor(message: string, path?: string) {
+    super(message);
+    this.name = "MalformedSessionRecordError";
+    this.path = path;
+  }
+}
+
+/** Inputs for {@link createSessionRecord}. */
+export interface CreateSessionRecordInput {
+  /** Provider type (registry key) that owns this session. */
+  providerType: string;
+  /** Codec-serialized session params (e.g. `{sessionId, cwd?}`). */
+  params: Record<string, unknown>;
+  /** Working directory the session ran in — transcript-lookup hint. */
+  cwd?: string | null;
+  /** Human-facing id (`sessionCodec.getDisplayId`), for UIs/logs. */
+  displayId?: string | null;
+}
+
+/**
+ * Build a `SessionRecord`, stamping `version` and a fresh `updatedAt`. This is
+ * the one blessed way to mint a record outside of `session.describe()`.
+ */
+export function createSessionRecord(input: CreateSessionRecordInput): SessionRecord {
+  return {
+    version: SESSION_RECORD_VERSION,
+    providerType: input.providerType,
+    params: input.params,
+    cwd: input.cwd ?? null,
+    displayId: input.displayId ?? null,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Structural guard for a `SessionRecord`. Tolerant of extra keys (a host may
+ * persist the record inside a larger row and read it back). Does not mutate.
+ */
+export function isSessionRecord(v: unknown): v is SessionRecord {
+  if (!isPlainObject(v)) return false;
+  if (v["version"] !== SESSION_RECORD_VERSION) return false;
+  if (typeof v["providerType"] !== "string" || v["providerType"].length === 0) return false;
+  if (!isPlainObject(v["params"])) return false;
+  if (v["cwd"] !== null && typeof v["cwd"] !== "string") return false;
+  if (v["displayId"] !== null && typeof v["displayId"] !== "string") return false;
+  if (typeof v["updatedAt"] !== "string") return false;
+  return true;
+}
+
+/**
+ * Assert `v` is a well-formed `SessionRecord`, narrowing the type. Throws
+ * `MalformedSessionRecordError` naming the first offending field.
+ */
+export function assertSessionRecord(v: unknown): asserts v is SessionRecord {
+  if (!isPlainObject(v)) {
+    throw new MalformedSessionRecordError("session record must be an object");
+  }
+  if (v["version"] !== SESSION_RECORD_VERSION) {
+    throw new MalformedSessionRecordError(
+      `session record version must be ${SESSION_RECORD_VERSION}; got ${JSON.stringify(v["version"])}`,
+      "version",
+    );
+  }
+  if (typeof v["providerType"] !== "string" || v["providerType"].length === 0) {
+    throw new MalformedSessionRecordError(
+      "session record providerType must be a non-empty string",
+      "providerType",
+    );
+  }
+  if (!isPlainObject(v["params"])) {
+    throw new MalformedSessionRecordError("session record params must be an object", "params");
+  }
+  if (v["cwd"] !== null && typeof v["cwd"] !== "string") {
+    throw new MalformedSessionRecordError("session record cwd must be a string or null", "cwd");
+  }
+  if (v["displayId"] !== null && typeof v["displayId"] !== "string") {
+    throw new MalformedSessionRecordError(
+      "session record displayId must be a string or null",
+      "displayId",
+    );
+  }
+  if (typeof v["updatedAt"] !== "string") {
+    throw new MalformedSessionRecordError(
+      "session record updatedAt must be an ISO timestamp string",
+      "updatedAt",
+    );
+  }
+}