@agentex/agent 0.0.27 → 0.0.29

package/src/sessions/exec-backed.ts

@@ -0,0 +1,169 @@
+import type {
+  AgentSession,
+  CancelResult,
+  ClearGoalResult,
+  ExecutionContext,
+  ExecutionResult,
+  GoalOptions,
+  GoalState,
+  ProviderCapabilities,
+  SendHandle,
+  SendOptions,
+  SessionCodec,
+  SessionContext,
+  SessionState,
+  SetGoalResult,
+  StopTaskResult,
+  StreamEvent,
+  TurnResult,
+} from "../types.js";
+import { GoalController, EMULATED_GOAL_CAPABILITY } from "../goals/index.js";
+import { uuidv7 } from "../utils/uuid.js";
+
+export interface ExecBackedSessionOptions {
+  providerType: string;
+  execute(ctx: ExecutionContext): Promise<ExecutionResult>;
+  sessionCodec: SessionCodec;
+  ctx: SessionContext;
+  capabilities?: Pick<ProviderCapabilities, "goals">;
+}
+
+function turnResult(result: ExecutionResult): TurnResult {
+  return {
+    summary: result.summary,
+    ...(result.usage ? { usage: result.usage } : {}),
+    costUsd: result.costUsd,
+    status: result.status === "blocked" ? "failed" : result.status,
+    errorCode: result.errorCode,
+    errorMessage: result.errorMessage,
+  };
+}
+
+export function createExecBackedSession(options: ExecBackedSessionOptions): AgentSession {
+  return new ExecBackedSession(options);
+}
+
+class ExecBackedSession implements AgentSession {
+  private _state: SessionState = "idle";
+  private params: Record<string, unknown> | null;
+  private active: AbortController | null = null;
+  private inFlight: Promise<TurnResult> | null = null;
+  private draining = false;
+  private readonly goals: GoalController;
+
+  constructor(private readonly options: ExecBackedSessionOptions) {
+    this.params = options.sessionCodec.deserialize(options.ctx.sessionParams ?? null);
+    this.goals = new GoalController({
+      providerType: options.providerType,
+      capability: options.capabilities?.goals ?? EMULATED_GOAL_CAPABILITY,
+      getSessionId: () => this.sessionId,
+      send: (message) => this.send(message),
+      dispatch: (event) => void Promise.resolve(options.ctx.onEvent?.(event)).catch(() => undefined),
+    });
+    if (options.ctx.signal) {
+      if (options.ctx.signal.aborted) void this.close();
+      else options.ctx.signal.addEventListener("abort", () => void this.close(), { once: true });
+    }
+  }
+
+  get sessionId(): string | null {
+    return this.options.sessionCodec.getDisplayId?.(this.params) ?? null;
+  }
+
+  get state(): SessionState {
+    return this._state;
+  }
+
+  async send(message: string, sendOptions?: SendOptions): Promise<SendHandle> {
+    if (this._state === "closed") throw new Error("Session is closed");
+    if (this.draining) throw new Error("Session is draining");
+    if (this.inFlight) throw new Error(`${this.options.providerType} session is busy`);
+    const uuid = uuidv7();
+    const result = this.run(message, sendOptions);
+    this.inFlight = result;
+    void result.then((settled) => this.goals.onTurnSettled(settled)).catch(() => undefined);
+    return { uuid, result };
+  }
+
+  private async run(message: string, sendOptions?: SendOptions): Promise<TurnResult> {
+    this._state = "thinking";
+    const controller = new AbortController();
+    this.active = controller;
+    const onAbort = () => controller.abort();
+    sendOptions?.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      const result = await this.options.execute({
+        prompt: message,
+        cwd: this.options.ctx.cwd,
+        env: this.options.ctx.env,
+        config: {
+          ...this.options.ctx.config,
+          ...(sendOptions?.timeoutSec !== undefined ? { timeoutSec: sendOptions.timeoutSec } : {}),
+        },
+        sessionParams: this.params,
+        signal: controller.signal,
+        onOutput: this.options.ctx.onOutput,
+        onLifecycle: (event) => this.options.ctx.onLifecycle?.(event),
+        onEvent: async (event: StreamEvent) => {
+          if (event.sessionId) {
+            this.params = this.options.sessionCodec.serialize({
+              sessionId: event.sessionId,
+              ...(this.options.ctx.cwd ? { cwd: this.options.ctx.cwd } : {}),
+            });
+          }
+          if (event.type === "tool_call") this._state = "tool_executing";
+          else if (event.type === "assistant" || event.type === "thinking") this._state = "thinking";
+          await this.options.ctx.onEvent?.(event);
+        },
+      });
+      if (result.clearSession) this.params = null;
+      if (result.sessionParams) this.params = this.options.sessionCodec.serialize(result.sessionParams);
+      return turnResult(result);
+    } finally {
+      sendOptions?.signal?.removeEventListener("abort", onAbort);
+      this.active = null;
+      this.inFlight = null;
+      this.restoreIdle();
+    }
+  }
+
+  private restoreIdle(): void {
+    if (this._state !== "closed") this._state = "idle";
+  }
+
+  async cancel(_uuid: string): Promise<CancelResult> {
+    return { cancelled: false };
+  }
+
+  async stopTask(_taskId: string): Promise<StopTaskResult> {
+    return { stopped: false };
+  }
+
+  setGoal(objective: string, goalOptions?: GoalOptions): Promise<SetGoalResult> {
+    return this.goals.setGoal(objective, goalOptions);
+  }
+
+  clearGoal(clearOptions?: { reason?: "cleared" | "blocked" }): Promise<ClearGoalResult> {
+    return this.goals.clearGoal(clearOptions);
+  }
+
+  getGoal(): GoalState | null {
+    return this.goals.getGoal();
+  }
+
+  async interrupt(): Promise<void> {
+    this.active?.abort();
+  }
+
+  async drain(): Promise<void> {
+    this.draining = true;
+    if (this.inFlight) await this.inFlight.catch(() => undefined);
+    await this.close();
+  }
+
+  async close(): Promise<void> {
+    this._state = "closed";
+    this.active?.abort();
+    if (this.inFlight) await this.inFlight.catch(() => undefined);
+  }
+}

package/src/sessions/history.ts

@@ -0,0 +1,76 @@
+import type {
+  HistoryAttachment,
+  HistoryCatchUpOptions,
+  HistoryCheckpoint,
+  SessionAttachment,
+} from "../types.js";
+
+interface FileCheckpointValue {
+  offset: number;
+  eventId?: string;
+}
+
+function decodeCheckpoint(
+  checkpoint: HistoryCheckpoint | undefined,
+  kind: string,
+): FileCheckpointValue | undefined {
+  if (!checkpoint) return undefined;
+  if (checkpoint.kind !== kind) {
+    throw new Error(`history checkpoint kind must be ${kind}`);
+  }
+  const value = checkpoint.value;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("history checkpoint value must be an object");
+  }
+  const offset = (value as Record<string, unknown>)["offset"];
+  const eventId = (value as Record<string, unknown>)["eventId"];
+  if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0) {
+    throw new Error("history checkpoint offset must be a non-negative safe integer");
+  }
+  if (eventId !== undefined && typeof eventId !== "string") {
+    throw new Error("history checkpoint eventId must be a string");
+  }
+  return { offset, ...(eventId ? { eventId } : {}) };
+}
+
+/** Adapt the legacy byte-offset transcript contract to the additive history API. */
+export function historyFromSessionAttachment(
+  providerType: string,
+  attachment: SessionAttachment,
+): HistoryAttachment {
+  const checkpointKind = `${providerType}:byte-offset:v1`;
+  return {
+    record: attachment.record,
+    historySource: attachment.transcript
+      ? { kind: "file", path: attachment.transcript.filePath }
+      : null,
+    lastTurn: attachment.lastTurn,
+    catchUp(options?: HistoryCatchUpOptions) {
+      if (options?.mode === "bounded_full_resync") {
+        options = { ...options, after: undefined };
+      }
+      const decoded = decodeCheckpoint(options?.after, checkpointKind);
+      return {
+        async *[Symbol.asyncIterator]() {
+          for await (const yielded of attachment.catchUp({
+            ...(decoded ? { fromOffset: decoded.offset } : {}),
+            ...(decoded?.eventId ? { sinceEventId: decoded.eventId } : {}),
+          })) {
+            yield {
+              event: yielded.event,
+              eventId: yielded.eventId,
+              checkpoint: {
+                kind: checkpointKind,
+                value: {
+                  offset: yielded.offset,
+                  ...(yielded.eventId ? { eventId: yielded.eventId } : {}),
+                },
+              },
+            };
+          }
+        },
+      };
+    },
+    resume: (ctx) => attachment.resume(ctx),
+  };
+}

package/src/sessions/index.ts

@@ -6,3 +6,6 @@ export {
   assertSessionRecord,
 } from "./record.js";
 export type { CreateSessionRecordInput } from "./record.js";
+export { historyFromSessionAttachment } from "./history.js";
+export { createExecBackedSession } from "./exec-backed.js";
+export type { ExecBackedSessionOptions } from "./exec-backed.js";

package/src/types.ts

@@ -93,6 +93,51 @@ export interface ProviderCapabilities {
    * Codex); absent elsewhere. See internal-docs/spec-durable-sessions.md.
    */
   durableSessions?: boolean;
+  /** Provider-neutral durable history through `attachHistory`. */
+  durableHistory?: boolean;
+  /** Read-only discovery and import of locally persisted sessions. */
+  localHistory?: boolean;
+  /** A persisted provider session can be resumed. */
+  resume?: boolean;
+  /** Models expose provider-native variants independently from effort. */
+  modelVariants?: boolean;
+  /** The provider can surface interactive permission requests. */
+  permissionRequests?: boolean;
+  /** The provider can surface structured questions. */
+  questionRequests?: boolean;
+  /** Ambient MCP configuration can be excluded by a proved mechanism. */
+  strictMcpIsolation?: boolean;
+  /** Connected upstream-provider credentials can be removed safely. */
+  upstreamProviderDisconnect?: boolean;
+  /** Selection changes can be applied without starting a new host chat. */
+  sessionModelChange?: boolean;
+  sessionVariantChange?: boolean;
+  sessionEffortChange?: boolean;
+  sessionModeChange?: boolean;
+}
+
+export type CapabilityStatus = "supported" | "missing" | "upgrade_required" | "degraded";
+
+export interface ProviderRuntimeContext {
+  cwd?: string;
+  env?: Record<string, string>;
+  config?: ProviderConfig;
+  refresh?: boolean;
+}
+
+export interface ProviderRuntimeReport {
+  binary: {
+    status: CapabilityStatus;
+    command: string | null;
+    version: string | null;
+    protocolProfile: string | null;
+    reason?: string;
+  };
+  capabilities: Partial<Record<keyof ProviderCapabilities, {
+    supported: boolean;
+    status: CapabilityStatus;
+    reason?: string;
+  }>>;
 }
 
 // ---------------------------------------------------------------------------
@@ -121,7 +166,7 @@ export interface ProviderCapabilities {
 export type GoalStatus = "active" | "paused" | "met" | "blocked" | "cleared";
 
 /** Why a `blocked` goal is blocked. */
-export type GoalBlockedReason = "budget" | "needs_input" | "max_iterations";
+export type GoalBlockedReason = "budget" | "needs_input" | "max_iterations" | "sentinel_error";
 
 /** Who last changed the goal state. */
 export type GoalSource = "host" | "model" | "sentinel" | "agentex";
@@ -165,6 +210,8 @@ export interface GoalState {
   source: GoalSource;
   /** Why a `blocked` goal is blocked. Absent unless status === "blocked". */
   blockedReason?: GoalBlockedReason;
+  /** Error from goal evaluation when blockedReason is `sentinel_error`. */
+  errorMessage?: string;
   /** Codex telemetry, when the provider reports it (reverse-engineered fields). */
   tokensUsed?: number;
   timeUsedSeconds?: number;
@@ -286,8 +333,12 @@ export interface ProviderModule {
    */
   resolveAuth(ctx?: AuthResolveContext): Promise<AuthReport>;
   sessionCodec?: SessionCodec;
-  /** List available models. Pass cacheTtlMs to cache results (0 = no cache, default). */
-  listModels?(options?: { cacheTtlMs?: number }): Promise<ProviderModel[]>;
+  /** List available models in a runtime context. */
+  listModels?(options?: ListModelsOptions): Promise<ProviderModel[]>;
+  /** Probe the selected binary and wire protocol for effective capabilities. */
+  probeCapabilities?(ctx?: ProviderRuntimeContext): Promise<ProviderRuntimeReport>;
+  /** Optional management surface for harness-owned upstream providers. */
+  upstreamProviders?: UpstreamProviderManager;
   /**
    * List the operating modes this provider exposes (see `AgentMode`). Present
    * only on providers with `capabilities.modes === true`. May spawn the agent
@@ -317,6 +368,10 @@ export interface ProviderModule {
    * never auto-invoked). See internal-docs/spec-durable-sessions.md.
    */
   attachSession?(record: SessionRecord, opts?: AttachOptions): Promise<SessionAttachment>;
+  /** Additive file-or-service durable history surface. */
+  attachHistory?(record: SessionRecord, opts?: AttachOptions): Promise<HistoryAttachment>;
+  /** Discover and read local sessions when their ids are not already known. */
+  localHistory?: import("./history/types.js").LocalHistoryOps;
 }
 
 // Result of looking up a transcript for a given session.
@@ -448,7 +503,7 @@ export interface CatchUpYield {
    * only bites Claude tool-call turns.)
    */
   offset: number;
-  /** Stable wire id for dedup vs live events (Claude); null when the provider has none (Codex). */
+  /** Stable replay id. Claude uses its wire id and file-backed Codex uses a deterministic synthetic id. */
   eventId: string | null;
 }
 
@@ -462,6 +517,8 @@ export interface CatchUpOptions {
 export interface AttachOptions {
   /** Env overlay for home-dir resolution (same vars the transcript helpers honor). */
   env?: Record<string, string>;
+  /** Runtime selection for service-backed attachment. */
+  config?: ProviderConfig;
 }
 
 /** Read-only reattachment to a session's durable state. See `attachSession`. */
@@ -484,6 +541,36 @@ export interface SessionAttachment {
   resume(ctx?: SessionContext): Promise<AgentSession>;
 }
 
+/** Opaque, provider-owned checkpoint for file or service history. */
+export interface HistoryCheckpoint {
+  kind: string;
+  value: unknown;
+}
+
+export type HistorySource =
+  | { kind: "file"; path: string }
+  | { kind: "service"; description: string };
+
+export interface HistoryCatchUpYield {
+  event: StreamEvent;
+  checkpoint: HistoryCheckpoint;
+  eventId: string | null;
+}
+
+export interface HistoryCatchUpOptions {
+  after?: HistoryCheckpoint;
+  mode?: "incremental" | "bounded_full_resync";
+}
+
+export interface HistoryAttachment {
+  record: SessionRecord;
+  historySource: HistorySource | null;
+  lastTurn: LastTurnStatus;
+  catchUp(opts?: HistoryCatchUpOptions): AsyncIterable<HistoryCatchUpYield>;
+  resume(ctx?: SessionContext): Promise<AgentSession>;
+  close?(): Promise<void>;
+}
+
 // Execution input
 export interface ExecutionContext {
   prompt: string;
@@ -567,9 +654,15 @@ export interface ProviderEndpointConfig {
 export interface ProviderConfig {
   command?: string;
   model?: string;
+  /** Provider-native model variant, independent from reasoning effort. */
+  modelVariant?: string;
   /** Provider reasoning effort. Claude maps this to `--effort`; Codex sends
    *  it as the app-server `turn/start.effort` override. */
   effort?: string;
+  /** Behavior when a host does not provide or loses its input callback. */
+  unattendedPermissionPolicy?: "allow" | "deny";
+  /** Deadline for a host to answer an observed permission or question. Default 300s. */
+  inputRequestTimeoutSec?: number;
   maxTurns?: number;
   /**
    * Hard runtime cap, in seconds.
@@ -1068,6 +1161,7 @@ export type StreamEvent =
       enforced: boolean;
       source: GoalSource;
       blockedReason?: GoalBlockedReason;
+      errorMessage?: string;
       tokensUsed?: number;
       timeUsedSeconds?: number;
       tokenBudget?: number;
@@ -1229,6 +1323,69 @@ export interface ProviderModel {
   id: string;
   name: string;
   provider?: string;
+  providerName?: string;
+  variants?: Array<{
+    id: string;
+    name: string;
+    description?: string;
+    isDefault?: boolean;
+    disabled?: boolean;
+  }>;
+  supportedEfforts?: string[];
+  defaultEffort?: string;
+  contextWindow?: number;
+  maxOutputTokens?: number;
+  inputCostPerMillion?: number;
+  outputCostPerMillion?: number;
+  supportsImages?: boolean;
+  supportsTools?: boolean;
+}
+
+export interface ListModelsOptions extends ProviderRuntimeContext {
+  cacheTtlMs?: number;
+}
+
+export interface UpstreamProvider {
+  id: string;
+  name: string;
+  connected: boolean;
+  authMethodIds: string[];
+}
+
+export interface ProviderAuthMethod {
+  id: string;
+  name: string;
+  type: "api_key" | "oauth";
+  prompts?: Array<{
+    id: string;
+    label: string;
+    type: "text" | "select";
+    options?: Array<{ value: string; label: string }>;
+  }>;
+}
+
+export interface ProviderAuthFlow {
+  id: string;
+  providerId: string;
+  url: string | null;
+  completion: "code" | "automatic";
+  instructions: string | null;
+  expiresAt: string;
+}
+
+export interface UpstreamProviderManager {
+  list(ctx?: ProviderRuntimeContext): Promise<UpstreamProvider[]>;
+  authMethods(providerId: string, ctx?: ProviderRuntimeContext): Promise<ProviderAuthMethod[]>;
+  setApiKey(providerId: string, key: string, ctx?: ProviderRuntimeContext): Promise<void>;
+  beginOAuth(
+    providerId: string,
+    methodId: string,
+    inputs?: Record<string, string>,
+    ctx?: ProviderRuntimeContext,
+  ): Promise<ProviderAuthFlow>;
+  completeOAuth(flowId: string, code?: string, ctx?: ProviderRuntimeContext): Promise<void>;
+  canDisconnect(providerId: string, ctx?: ProviderRuntimeContext): Promise<boolean>;
+  disconnect(providerId: string, ctx?: ProviderRuntimeContext): Promise<void>;
 }
 
 // MCP server configuration
@@ -1496,6 +1653,8 @@ export interface AgentSession {
    * `capabilities.durableSessions === true`.
    */
   describe?(): SessionRecord | null;
+  /** Additive provider-neutral durable-history identity. */
+  describeHistory?(): SessionRecord | null;
 }
 
 /** Result of a single turn within a session. */

package/src/utils/auth.ts

@@ -89,7 +89,7 @@ export function detectAuth(providerType: string, env: Record<string, string>): R
       return { method: "subscription", billingType: "subscription" };
     }
     case "cursor": {
-      if (hasEnv(env, "CURSOR_API_KEY") || hasEnv(env, "OPENAI_API_KEY")) {
+      if (hasEnv(env, "CURSOR_API_KEY")) {
         return { method: "api_key", billingType: "api" };
       }
       return { method: "subscription", billingType: "subscription" };
@@ -435,21 +435,50 @@ async function resolveGeminiAuth(ctx?: AuthResolveContext): Promise<AuthReport>
 }
 
 // ---------------------------------------------------------------------------
-// Cursor / OpenCode / Pi / OpenClaw / Process — no CLI auth commands;
-// straightforward env-only reports with binary status when applicable.
+// Cursor uses its selected binary's `status` command. Other providers in this
+// section use environment or native-store presence reports.
 // ---------------------------------------------------------------------------
 
 async function resolveCursorAuth(ctx?: AuthResolveContext): Promise<AuthReport> {
   const env = buildEnv(ctx?.env);
   const binary = await checkBinary("agent", ctx?.command, env);
+  const apiKey = {
+    method: "api_key" as const,
+    source: { kind: "env" as const, var: "CURSOR_API_KEY" },
+    present: hasEnv(env, "CURSOR_API_KEY"),
+  };
+  let nativePresent = false;
+  let usedCli = false;
+  if (binary.installed && binary.resolvedPath) {
+    try {
+      const result = await runChildProcess({
+        runId: "cursor-auth-status",
+        command: binary.resolvedPath,
+        args: [...binary.prefixArgs, "status"],
+        cwd: process.cwd(),
+        env,
+        timeoutSec: 10,
+      });
+      const output = `${result.stdout}\n${result.stderr}`;
+      nativePresent = result.exitCode === 0 && /logged\s+in|authenticated|account\s*:/i.test(output)
+        && !/not\s+logged\s+in|unauthenticated/i.test(output);
+      usedCli = true;
+    } catch {
+      // Presence remains unknown and false for an unsupported old binary.
+    }
+  }
   return {
     providerType: "cursor",
     binary: stripPrefixArgs(binary),
     options: [
-      { method: "api_key", source: { kind: "env", var: "CURSOR_API_KEY" }, present: hasEnv(env, "CURSOR_API_KEY") },
-      { method: "api_key", source: { kind: "env", var: "OPENAI_API_KEY" }, present: hasEnv(env, "OPENAI_API_KEY") },
+      apiKey,
+      {
+        method: "subscription",
+        source: { kind: "cli", command: "agent status" },
+        present: nativePresent,
+      },
     ],
-    source: "filesystem",
+    source: usedCli ? "cli" : "filesystem",
   };
 }
 

package/src/utils/binary.ts

@@ -28,8 +28,11 @@ const COMMON_PATHS_UNIX: Record<string, string[]> = {
   ],
   agent: [
     path.join(os.homedir(), ".local", "bin", "agent"),
+    path.join(os.homedir(), ".local", "bin", "cursor-agent"),
     "/usr/local/bin/agent",
+    "/usr/local/bin/cursor-agent",
     path.join(os.homedir(), ".npm-global", "bin", "agent"),
+    path.join(os.homedir(), ".npm-global", "bin", "cursor-agent"),
   ],
   opencode: [
     path.join(os.homedir(), ".local", "bin", "opencode"),

package/src/utils/endpoint.ts

@@ -158,13 +158,13 @@ function translateCodexEndpoint(e: ProviderEndpointConfig): EndpointTranslation
     // name), never argv: argv is world-readable via `ps` and a header can carry
     // a secret (Authorization, X-API-Key). Mirrors why the claude provider
     // stages MCP headers to a 0600 file instead of the command line. Header
-    // names are assumed TOML bare keys (letters/digits/`-`/`_`), which real HTTP
-    // header tokens are — a name with a `.` would nest as a sub-table.
+    // names are emitted as quoted TOML path segments because valid HTTP token
+    // characters such as `.` must not become nested configuration paths.
     let i = 0;
     for (const [name, value] of Object.entries(e.headers)) {
       const headerEnv = `${CODEX_CUSTOM_HEADER_ENV_PREFIX}${i++}`;
       env[headerEnv] = value;
-      set(`model_providers.${id}.env_http_headers.${name}`, headerEnv);
+      set(`model_providers.${id}.env_http_headers.${JSON.stringify(name)}`, headerEnv);
     }
   }
   // modelMap intentionally ignored — Codex has no tier aliases.