@agentex/agent 0.0.23 → 0.0.26

package/src/goals/sentinel.ts

@@ -0,0 +1,90 @@
+import type {
+  GoalSentinel,
+  GoalSentinelContext,
+  GoalSentinelVerdict,
+  TurnResult,
+} from "../types.js";
+
+/** Normalize a sentinel's `boolean | {met,nudge}` return into a verdict. */
+export async function runSentinel(
+  sentinel: GoalSentinel,
+  ctx: GoalSentinelContext,
+): Promise<GoalSentinelVerdict> {
+  const out = await sentinel(ctx);
+  if (typeof out === "boolean") return { met: out };
+  return { met: out.met === true, ...(out.nudge ? { nudge: out.nudge } : {}) };
+}
+
+/**
+ * The objective doubles as the first turn's directive (matching native `/goal`,
+ * which starts a turn immediately with the condition). Kept verbatim so a goal
+ * like "All tests pass under `pnpm test`" reads naturally as a task.
+ */
+export function buildKickoffMessage(objective: string): string {
+  return objective;
+}
+
+/** Continuation message sent when the sentinel judges the goal not-yet-met. */
+export function defaultNudge(objective: string, iterations: number): string {
+  return [
+    `The goal is not yet satisfied (attempt ${iterations + 1}). Keep working until it is fully met, then stop.`,
+    "",
+    "Goal:",
+    objective,
+  ].join("\n");
+}
+
+/**
+ * Prompt for the default sentinel's self-assessment turn. The model must answer
+ * with a single leading token so the parse is unambiguous.
+ */
+export function buildAssessmentPrompt(objective: string): string {
+  return [
+    "Assess ONLY whether the goal below is now fully and verifiably met by the work done so far in this conversation.",
+    "Answer with exactly one word on the first line: YES if it is fully met, otherwise NO.",
+    "Do not perform any further work; do not edit files. Just judge.",
+    "",
+    "Goal:",
+    objective,
+  ].join("\n");
+}
+
+/**
+ * Parse a yes/no self-assessment answer. Conservative: only an explicit
+ * affirmative ("yes"/"met"/"complete"/"done"/"satisfied" as the first token, or
+ * a clear standalone "YES") counts as met. Anything ambiguous → not met, so the
+ * loop keeps working rather than declaring premature success.
+ */
+export function parseAssessment(text: string): boolean {
+  const trimmed = text.trim().toLowerCase();
+  if (!trimmed) return false;
+  const firstToken = (trimmed.split(/[\s,.:!]+/)[0] ?? "").replace(/[^a-z]/g, "");
+  if (["no", "not", "incomplete", "unmet", "false"].includes(firstToken)) return false;
+  if (["yes", "met", "complete", "completed", "done", "satisfied", "true"].includes(firstToken)) {
+    return true;
+  }
+  // Fall back to a strict scan for an unambiguous affirmative phrase.
+  return /\b(goal\s+is\s+)?(fully\s+)?(met|complete|completed|satisfied)\b/.test(trimmed)
+    && !/\bnot\b/.test(trimmed);
+}
+
+/**
+ * Build the library's default sentinel: ask the running provider to self-assess
+ * whether the goal is met. Borrows Claude's design (judge from what the working
+ * model surfaced) but uses the same session — so it adds a meta-turn to the
+ * transcript. NOTE: the meta-turn runs with the session's normal tool/permission
+ * grant; the prompt ASKS the model not to act, but that is not enforced, so this
+ * is not a true read-only judge. Hosts with a deterministic check (e.g. run
+ * tests) should pass their own `sentinel`; this is the of-last-resort default.
+ *
+ * `metaSend` runs a turn and resolves with its TurnResult. The controller wires
+ * it so the meta-turn's own settle is ignored by the goal loop (no recursion).
+ */
+export function createDefaultSentinel(deps: {
+  metaSend: (message: string) => Promise<TurnResult>;
+}): GoalSentinel {
+  return async (ctx: GoalSentinelContext): Promise<GoalSentinelVerdict> => {
+    const turn = await deps.metaSend(buildAssessmentPrompt(ctx.objective));
+    return { met: parseAssessment(turn.summary ?? "") };
+  };
+}

package/src/index.ts

@@ -0,0 +1,270 @@
+// Functions
+export { getProvider, listProviders, registerProvider } from "./registry.js";
+export {
+  defineDerivedProvider,
+  loadProvidersFromConfig,
+  registerAcpFactory,
+  MalformedProviderConfigError,
+} from "./derived.js";
+export type { DerivedProviderConfig, AcpFactory } from "./derived.js";
+export { acpProvider } from "./providers/acp/index.js";
+export type { AcpProviderConfig } from "./providers/acp/index.js";
+export type { AcpTransformers } from "./providers/acp/session.js";
+export {
+  runHttpAgent,
+  httpAgentProvider,
+  httpAgentSessionCodec,
+} from "./providers/_shared/http-agent.js";
+export type { HttpAgentOptions } from "./providers/_shared/http-agent.js";
+export { renderTemplate } from "./utils/template.js";
+export { redactEnvForLogs } from "./utils/env.js";
+export {
+  translateEndpoint,
+  CODEX_CUSTOM_PROVIDER_ID,
+  CODEX_CUSTOM_KEY_ENV,
+} from "./utils/endpoint.js";
+export type { EndpointTranslation } from "./utils/endpoint.js";
+export { parseAskUserQuestion } from "./utils/ask-user-question.js";
+export { parseExitPlanMode } from "./utils/exit-plan-mode.js";
+export { aggregateUsage } from "./types.js";
+export {
+  resolveInstructions,
+  installInstructions,
+  removeInstructions,
+  resolveInstructionTargets,
+  upsertManagedBlock,
+  stripManagedBlock,
+} from "./utils/instructions.js";
+export type {
+  InstallInstructionsOptions,
+  InstructionStatus,
+  InstructionInstallEntry,
+  InstructionInstallResult,
+  InstructionTarget,
+  RemoveInstructionsOptions,
+  InstructionRemoveStatus,
+  InstructionRemoveEntry,
+  InstructionRemoveResult,
+  ManagedBlockOptions,
+} from "./utils/instructions.js";
+export { getRuntimeHomeEnvVar, getDefaultRuntimeHome } from "./utils/runtime-homes.js";
+export { findBinary, ensureCommandResolvable, clearBinaryCache } from "./utils/binary.js";
+export type { ResolvedBinary } from "./utils/binary.js";
+export {
+  detectAuth,
+  resolveAuthForProvider,
+  clearAuthCache,
+  hasSubscription,
+  hasApiKey,
+  hasBedrock,
+  isLoggedIn,
+  loginCommandFor,
+} from "./utils/auth.js";
+export type { ResolvedAuth } from "./utils/auth.js";
+export { prepareWorkspace } from "./utils/workspace.js";
+export type { WorkspaceOptions, PreparedWorkspace, DiffOptions } from "./utils/workspace.js";
+export { withTempConfig } from "./utils/runtime-config.js";
+export type { TempConfigResult, TempConfigOptions } from "./utils/runtime-config.js";
+export { executeAll } from "./utils/execute-all.js";
+export type { ExecuteAllOptions, ExecuteAllTask } from "./utils/execute-all.js";
+export {
+  getClaudeUnknownDetails,
+  getClaudeTaskDetails,
+  classifyClaudeAuthFromResult,
+  CLAUDE_LOGIN_COMMAND,
+} from "./providers/claude/parse.js";
+export type {
+  ClaudeTaskDetails,
+  ClaudeTaskUsage,
+  ClaudeTaskStatus,
+} from "./providers/claude/parse.js";
+export {
+  getClaudeTranscriptPath,
+  findClaudeTranscriptBySessionId,
+  readClaudeTranscript,
+  peekClaudeTranscript,
+  claudeTranscriptOps,
+  sanitizeProjectPath,
+  resolveClaudeHome,
+  canonicalizeCwd,
+  MAX_SANITIZED_LENGTH,
+} from "./providers/claude/transcript.js";
+export type {
+  GetClaudeTranscriptPathOptions,
+  ClaudeTranscriptLocation,
+  FindClaudeTranscriptOptions,
+  FoundClaudeTranscript,
+  ReadClaudeTranscriptOptions,
+  ClaudeTranscriptYield,
+  ClaudePeekResult,
+} from "./providers/claude/transcript.js";
+export {
+  getCodexTranscriptPath,
+  readCodexTranscript,
+  peekCodexTranscript,
+  readCodexCwd,
+  codexTranscriptOps,
+  parseCodexLine,
+  resolveCodexHome,
+} from "./providers/codex/transcript.js";
+export { codexLineToStreamEvents } from "./providers/codex/transcript-normalize.js";
+export type {
+  GetCodexTranscriptPathOptions,
+  CodexTranscriptLocation,
+  ReadCodexTranscriptOptions,
+  CodexTranscriptYield,
+  CodexTranscriptLine,
+  CodexPeekResult,
+} from "./providers/codex/transcript.js";
+
+// Skills
+export {
+  installSkills,
+  removeSkills,
+  listInstalledSkills,
+  resolveSkillsHome,
+  resolveSkillsWorkspace,
+  resolveNativeSkillsHome,
+  resolveNativeSkillsWorkspace,
+  ensureSkillSymlink,
+} from "./utils/skills.js";
+export {
+  commandInventoryFromEvent,
+  discoverSkillCommands,
+  reconcileSkillCommands,
+  formatSlashInvocation,
+  invokeSkill,
+  buildExpandedSkillPrompt,
+} from "./utils/skill-commands.js";
+
+// Types
+export type {
+  ProviderModule,
+  ProviderCapabilities,
+  AgentMode,
+  ListModesOptions,
+  ExecutionContext,
+  ExecutionResult,
+  ExecutionStatus,
+  ProviderConfig,
+  ProviderEndpointConfig,
+  McpServerConfig,
+  StreamEvent,
+  SessionCodec,
+  SessionState,
+  TokenUsage,
+  ModelUsage,
+  RateLimitInfo,
+  BaseStreamEventFields,
+  LifecycleEvent,
+  QuotaStatus,
+  QuotaContext,
+  AuthMethod,
+  AuthSource,
+  AuthOption,
+  AuthReport,
+  AuthResolveContext,
+  AuthIdentity,
+  AuthRequiredReason,
+  BinaryStatus,
+  ProviderModel,
+  SessionContext,
+  AgentSession,
+  SendHandle,
+  SendOptions,
+  CancelResult,
+  StopTaskResult,
+  TurnResult,
+  UserInputRequest,
+  UserInputResponse,
+  ElicitationRequest,
+  ElicitationResponse,
+  HookCallbackRequest,
+  HookCallbackResponse,
+  TranscriptOps,
+  TranscriptYield,
+  TranscriptPeek,
+  FoundTranscript,
+  GoalStatus,
+  GoalBlockedReason,
+  GoalSource,
+  GoalCapability,
+  GoalState,
+  GoalOptions,
+  SetGoalResult,
+  ClearGoalResult,
+  GoalSentinel,
+  GoalSentinelVerdict,
+  GoalSentinelContext,
+} from "./types.js";
+
+// Goals
+export {
+  GoalController,
+  EMULATED_GOAL_CAPABILITY,
+  GOAL_OBJECTIVE_MAX,
+  CODEX_GOAL_TOOLS,
+  isTerminalGoalStatus,
+  goalStateFromEvent,
+  latestGoalFromEvents,
+  normalizeClaudeGoalAttachment,
+  normalizeCodexGoalStatus,
+  normalizeCodexGoalRecord,
+  createDefaultSentinel,
+  parseAssessment,
+} from "./goals/index.js";
+export type {
+  GoalControllerDeps,
+  GoalStatusEvent,
+  NormalizedGoalFields,
+} from "./goals/index.js";
+
+// Durable sessions
+export {
+  SESSION_RECORD_VERSION,
+  MalformedSessionRecordError,
+  createSessionRecord,
+  isSessionRecord,
+  assertSessionRecord,
+} from "./sessions/index.js";
+export type { CreateSessionRecordInput } from "./sessions/index.js";
+export type {
+  SessionRecord,
+  LastTurnStatus,
+  CatchUpYield,
+  CatchUpOptions,
+  AttachOptions,
+  SessionAttachment,
+} from "./types.js";
+
+export type {
+  AskUserQuestion,
+  QuestionOption,
+} from "./utils/ask-user-question.js";
+
+export type { ExitPlanModeRequest } from "./utils/exit-plan-mode.js";
+
+export type {
+  SkillRuntime,
+  SkillLocation,
+  SkillChannel,
+  InstallSkillsOptions,
+  SkillInstallEntry,
+  SkillInstallResult,
+  RemoveSkillsOptions,
+  SkillRemoveEntry,
+  SkillRemoveResult,
+  InstalledSkill,
+} from "./utils/skills.js";
+
+export type {
+  SkillCommandSource,
+  SkillCommandExecution,
+  SkillCommandDescriptor,
+  RuntimeCommandInventory,
+  SkillCommandDiagnostic,
+  DiscoverSkillCommandsOptions,
+  DiscoverSkillCommandsResult,
+  ReconcileSkillCommandsOptions,
+  InvokeSkillOptions,
+} from "./utils/skill-commands.js";

package/src/providers/_shared/http-agent.ts

@@ -0,0 +1,304 @@
+import type {
+  AuthReport,
+  ExecutionContext,
+  ExecutionResult,
+  ProviderModule,
+  SessionCodec,
+} from "../../types.js";
+import { uuidv7 } from "../../utils/uuid.js";
+
+/**
+ * Reusable "remote HTTP agent" adapter — the pattern OpenClaw encodes and the
+ * shape any gateway-backed agent reuses: resolve a gateway URL (per-call command
+ * override → saved sessionParams → default), round-trip a session key through
+ * `sessionParams`, POST the prompt, map 401/403 to an `auth_required` event, and
+ * bound the request with an AbortController timeout.
+ */
+export interface HttpAgentOptions {
+  /** Provider id (used on events + the result). */
+  providerType: string;
+  /** Gateway base URL used when neither `config.command` nor a saved URL is set. */
+  defaultBaseUrl: string;
+  /** Path appended to the base URL for the run endpoint (e.g. "/api/agent/run"). */
+  runPath: string;
+  /** Recovery command surfaced on `auth_required` (e.g. "openclaw login"). */
+  loginCommand?: string;
+  /** Build the JSON request body. Default: `{ prompt, sessionKey?, model? }`. */
+  buildBody?: (input: { prompt: string; sessionKey: string | null; model: string | null }) => Record<string, unknown>;
+  /** Pull the summary text from the gateway response. Default: summary ?? result ?? output. */
+  extractSummary?: (response: Record<string, unknown>) => string | null;
+  /** Pull the (possibly new) session key from the response. Default: `response.sessionKey ?? prev`. */
+  extractSessionKey?: (response: Record<string, unknown>, prev: string | null) => string | null;
+  /** Pull the model id from the response. Default: `response.model ?? fallback`. */
+  extractModel?: (response: Record<string, unknown>, fallback: string | null) => string | null;
+  /** Pull the cost from the response. Default: `response.costUsd` when numeric. */
+  extractCost?: (response: Record<string, unknown>) => number | null;
+}
+
+function str(v: unknown): string | null {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+function defaultSummary(r: Record<string, unknown>): string | null {
+  return str(r["summary"]) ?? str(r["result"]) ?? str(r["output"]);
+}
+
+/** Resolve the session key from session params (sessionKey / session_key). */
+function readSessionKey(sessionParams: Record<string, unknown> | null | undefined): string | null {
+  if (!sessionParams) return null;
+  return str(sessionParams["sessionKey"]) ?? str(sessionParams["session_key"]);
+}
+
+/** Execute a single turn against a remote HTTP agent gateway. */
+export async function runHttpAgent(
+  opts: HttpAgentOptions,
+  ctx: ExecutionContext,
+): Promise<ExecutionResult> {
+  const runId = ctx.runId ?? uuidv7();
+  const model = ctx.model ?? ctx.config?.model ?? null;
+  const config = ctx.config ?? {};
+  const startedAt = new Date().toISOString();
+  const startMs = Date.now();
+
+  const savedGatewayUrl = str(ctx.sessionParams?.["gatewayUrl"]);
+  const gatewayUrl = config.command?.trim() || savedGatewayUrl || opts.defaultBaseUrl;
+  const endpoint = gatewayUrl.replace(/\/$/, "") + opts.runPath;
+
+  const sessionKey = readSessionKey(ctx.sessionParams);
+  const body = opts.buildBody
+    ? opts.buildBody({ prompt: ctx.prompt, sessionKey, model })
+    : {
+        prompt: ctx.prompt,
+        ...(sessionKey ? { sessionKey } : {}),
+        ...(model ? { model } : {}),
+      };
+
+  const abortController = new AbortController();
+  let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+  let timedOut = false;
+  if (config.timeoutSec && config.timeoutSec > 0) {
+    timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      abortController.abort();
+    }, config.timeoutSec * 1000);
+  }
+  // Chain a caller-supplied signal (a caller abort is distinct from a timeout).
+  if (ctx.signal) {
+    if (ctx.signal.aborted) abortController.abort();
+    else ctx.signal.addEventListener("abort", () => abortController.abort(), { once: true });
+  }
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: abortController.signal,
+    });
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      const isAuth = response.status === 401 || response.status === 403;
+      if (isAuth && ctx.onEvent) {
+        try {
+          await ctx.onEvent({
+            type: "auth_required",
+            httpStatus: response.status,
+            reason: "unknown",
+            loginCommand: opts.loginCommand ?? `${opts.providerType} login`,
+            message: errorText || null,
+            timestamp: new Date().toISOString(),
+            providerType: opts.providerType,
+            sessionId: sessionKey ?? null,
+            messageId: null,
+            eventId: null,
+            turnId: null,
+            parentToolCallId: null,
+            raw: { status: response.status, body: errorText },
+          });
+        } catch {
+          /* swallow */
+        }
+      }
+      return {
+        runId,
+        exitCode: 1,
+        signal: null,
+        status: "failed",
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs: Date.now() - startMs,
+        errorMessage: `${opts.providerType} gateway returned ${response.status}: ${errorText}`,
+        errorCode: isAuth ? "auth_required" : null,
+        costUsd: null,
+        model,
+        summary: null,
+        sessionParams: sessionKey ? { sessionKey, gatewayUrl } : null,
+        sessionDisplayId: sessionKey,
+        clearSession: false,
+        billingType: null,
+      };
+    }
+
+    const result = (await response.json()) as Record<string, unknown>;
+    const newSessionKey = opts.extractSessionKey
+      ? opts.extractSessionKey(result, sessionKey)
+      : (str(result["sessionKey"]) ?? sessionKey);
+    const summary = (opts.extractSummary ?? defaultSummary)(result);
+    const resolvedModel = opts.extractModel
+      ? opts.extractModel(result, model)
+      : (str(result["model"]) ?? model);
+    const costUsd = opts.extractCost
+      ? opts.extractCost(result)
+      : typeof result["costUsd"] === "number"
+        ? (result["costUsd"] as number)
+        : null;
+
+    if (ctx.onEvent && summary) {
+      try {
+        await ctx.onEvent({
+          type: "result",
+          text: summary,
+          costUsd,
+          isError: false,
+          stopReason: null,
+          terminalReason: null,
+          numTurns: null,
+          durationMs: null,
+          timestamp: new Date().toISOString(),
+          providerType: opts.providerType,
+          sessionId: newSessionKey ?? null,
+          messageId: null,
+          eventId: null,
+          turnId: null,
+          parentToolCallId: null,
+          raw: result,
+        });
+      } catch {
+        /* swallow */
+      }
+    }
+
+    return {
+      runId,
+      exitCode: 0,
+      signal: null,
+      status: "completed",
+      startedAt,
+      completedAt: new Date().toISOString(),
+      durationMs: Date.now() - startMs,
+      errorMessage: null,
+      errorCode: null,
+      costUsd,
+      model: resolvedModel,
+      summary,
+      sessionParams: newSessionKey ? { sessionKey: newSessionKey, gatewayUrl } : null,
+      sessionDisplayId: newSessionKey,
+      clearSession: false,
+      billingType: null,
+      raw: result,
+    };
+  } catch (err) {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+    if (err instanceof Error && err.name === "AbortError") {
+      // A timeout and a caller-supplied signal abort both surface as AbortError;
+      // distinguish them so consumers can tell a deadline from a cancellation.
+      const isTimeout = timedOut;
+      return {
+        runId,
+        exitCode: null,
+        signal: null,
+        status: isTimeout ? "timeout" : "aborted",
+        startedAt,
+        completedAt: new Date().toISOString(),
+        durationMs: Date.now() - startMs,
+        errorMessage: isTimeout ? `Timed out after ${config.timeoutSec ?? 0}s` : "Aborted by caller",
+        errorCode: isTimeout ? "timeout" : "aborted",
+        costUsd: null,
+        model,
+        summary: null,
+        sessionParams: sessionKey ? { sessionKey, gatewayUrl } : null,
+        sessionDisplayId: sessionKey,
+        clearSession: false,
+        billingType: null,
+      };
+    }
+    // A transient network error (DNS, reset) is recoverable — preserve the
+    // session key / gateway so the caller can resume rather than losing it.
+    return {
+      runId,
+      exitCode: null,
+      signal: null,
+      status: "failed",
+      startedAt,
+      completedAt: new Date().toISOString(),
+      durationMs: Date.now() - startMs,
+      errorMessage: err instanceof Error ? err.message : `${opts.providerType} execution failed`,
+      errorCode: null,
+      costUsd: null,
+      model,
+      summary: null,
+      sessionParams: sessionKey ? { sessionKey, gatewayUrl } : null,
+      sessionDisplayId: sessionKey,
+      clearSession: false,
+      billingType: null,
+    };
+  }
+}
+
+/** Session codec for HTTP-agent providers — round-trips `{ sessionKey, gatewayUrl }`. */
+export const httpAgentSessionCodec: SessionCodec = {
+  deserialize(raw: unknown): Record<string, unknown> | null {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+    const obj = raw as Record<string, unknown>;
+    const sessionKey = str(obj["sessionKey"]) ?? str(obj["session_key"]);
+    if (!sessionKey) return null;
+    const gatewayUrl = str(obj["gatewayUrl"]);
+    return { sessionKey, ...(gatewayUrl ? { gatewayUrl } : {}) };
+  },
+  serialize(params: Record<string, unknown> | null): Record<string, unknown> | null {
+    if (!params) return null;
+    const sessionKey = str(params["sessionKey"]) ?? str(params["session_key"]);
+    if (!sessionKey) return null;
+    const gatewayUrl = str(params["gatewayUrl"]);
+    return { sessionKey, ...(gatewayUrl ? { gatewayUrl } : {}) };
+  },
+  getDisplayId(params: Record<string, unknown> | null): string | null {
+    if (!params) return null;
+    return str(params["sessionKey"]) ?? str(params["session_key"]);
+  },
+};
+
+/** Build a `ProviderModule` for a remote HTTP agent gateway. */
+export function httpAgentProvider(opts: HttpAgentOptions): ProviderModule {
+  async function resolveAuth(): Promise<AuthReport> {
+    // The gateway is a URL, not a local binary, so we can't probe presence here.
+    return {
+      providerType: opts.providerType,
+      binary: { installed: true },
+      options: [],
+      source: "filesystem",
+    };
+  }
+  return {
+    type: opts.providerType,
+    capabilities: {
+      sessions: false,
+      modelDiscovery: false,
+      quotaProbing: false,
+      mcp: false,
+      skills: false,
+      instructions: false,
+      workspace: false,
+      planMode: false,
+      concurrentSend: false,
+      cancelQueuedMessage: false,
+      stopTask: false,
+      modes: false,
+    },
+    execute: (ctx) => runHttpAgent(opts, ctx),
+    resolveAuth,
+    sessionCodec: httpAgentSessionCodec,
+  };
+}