@agent-native/core 0.94.2 → 0.95.0

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2166
-- template files: 5364
+- template files: 5365

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @agent-native/core
 
+## 0.95.0
+
+### Minor Changes
+
+- 2308575: Add an OpenAI-compatible PR visual recap backend for DeepSeek, Kimi, and other compatible providers.
+
+## 0.94.3
+
+### Patch Changes
+
+- 48d8471: Keep Slack agent task cards active through deferred cross-agent work, show durable progress, and deliver the true final result instead of treating interim artifacts as complete.
+- 48d8471: Keep completed realtime voice turns in their originating chat, restore that chat safely when voice ends, and expose live audio activity to the voice dock.
+- 48d8471: Accept canonical Content document links returned by successful read-only actions as A2A artifact proof while continuing to reject mismatched or unproven URLs.
+
 ## 0.94.2
 
 ### Patch Changes

package/corpus/core/docs/content/pr-visual-recap.mdx

@@ -7,7 +7,7 @@ description: "A GitHub Action that runs your repo's visual-recap skill on every
 
 PR Visual Recap is a GitHub Action that turns every pull request into a **visual code review**. On each push, an LLM coding agent runs the latest bundled [`visual-recap`](/docs/template-plan) skill (or your repo's committed copy when `VISUAL_RECAP_SKILL_SOURCE=repo`) against the PR diff, publishes a structured recap plan to the hosted Plans app, shows an informational `Visual Recap` check while it runs, and upserts **one sticky PR comment** that links to the interactive plan with an **inline screenshot** embedded right in the comment.
 
-This is not a deterministic diff renderer. The action invokes a real coding agent (Claude Code CLI by default, or OpenAI Codex CLI) that reads the change, decides what matters, and authors the recap by calling the Plans MCP tool `create-visual-recap` — the same tool the `/visual-recap` slash command uses. You get a high-altitude, schema/API/before-after view of the change instead of a wall of raw diff.
+This is not a deterministic diff renderer. The action invokes a real coding agent (Claude Code CLI by default, OpenAI Codex CLI, or Agent-Native Code with an OpenAI-compatible provider) that reads the change, decides what matters, and authors the recap by calling the Plans MCP tool `create-visual-recap` — the same tool the `/visual-recap` slash command uses. You get a high-altitude, schema/API/before-after view of the change instead of a wall of raw diff.
 
 The recap is **informational and non-blocking**. It creates a check row so reviewers can see that generation is in progress, but it is not a required check, it never blocks the PR, and it never replaces reading the actual diff. The sticky comment is a review aid, not a sign-off.
 
@@ -36,7 +36,7 @@ On each PR push, the workflow:
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-node">
     Coding agent<br /><small class="diagram-muted"
-      >Claude Code / Codex reads diff</small
+      >configured backend reads diff</small
     >
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
@@ -127,28 +127,32 @@ pins its committed `visual-recap` folder, set the repository variable
 
 Choose which coding agent runs the skill with the `VISUAL_RECAP_AGENT` repository variable:
 
-| `VISUAL_RECAP_AGENT` | Coding agent     | Required API key    |
-| -------------------- | ---------------- | ------------------- |
-| `claude` _(default)_ | Claude Code CLI  | `ANTHROPIC_API_KEY` |
-| `codex`              | OpenAI Codex CLI | `OPENAI_API_KEY`    |
+| `VISUAL_RECAP_AGENT` | Coding agent                            | Required API key       | Required variables                            |
+| -------------------- | --------------------------------------- | ---------------------- | --------------------------------------------- |
+| `claude` _(default)_ | Claude Code CLI                         | `ANTHROPIC_API_KEY`    | —                                             |
+| `codex`              | OpenAI Codex CLI                        | `OPENAI_API_KEY`       | —                                             |
+| `openai-compatible`  | Agent-Native Code + compatible provider | `VISUAL_RECAP_API_KEY` | `VISUAL_RECAP_BASE_URL`, `VISUAL_RECAP_MODEL` |
 
 If the variable is unset, the action uses `claude`.
 
 ## Model and reasoning
 
-Beyond the backend, two repository variables tune _how_ the agent runs:
+Beyond the backend, these repository variables tune how the agent runs:
 
-- **`VISUAL_RECAP_MODEL`** pins the model passed to the CLI (`--model`) — for example `gpt-5.6-sol` for Codex, or a Claude model id. Leave it unset to use the CLI's own default model.
+- **`VISUAL_RECAP_MODEL`** pins the model passed to the CLI (`--model`) — for example `gpt-5.6-sol` for Codex, a Claude model id, or `deepseek-chat` for DeepSeek. It is required for `openai-compatible`; Claude and Codex may leave it unset to use their CLI default.
 - **`VISUAL_RECAP_REASONING`** sets the reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. It applies to the Codex backend; Claude's reasoning is model-driven, so this variable is ignored there.
+- **`VISUAL_RECAP_BASE_URL`** selects the HTTP(S) base URL for the `openai-compatible` backend. Use the provider's OpenAI-compatible endpoint, such as DeepSeek or Kimi, without embedding credentials in the URL.
 - **`VISUAL_RECAP_SKILL_SOURCE`** controls prompt freshness: `auto`/unset uses the latest bundled skill guidance, while `repo` pins to the committed repo-local `visual-recap` skill folder.
 
 For example, to run the recap on Codex with GPT-5.6 Sol at high reasoning, set the repository variables `VISUAL_RECAP_AGENT=codex`, `VISUAL_RECAP_MODEL=gpt-5.6-sol`, and `VISUAL_RECAP_REASONING=high`.
 
+For DeepSeek, set `VISUAL_RECAP_AGENT=openai-compatible`, `VISUAL_RECAP_BASE_URL=https://api.deepseek.com/v1`, `VISUAL_RECAP_MODEL=deepseek-chat`, and the `VISUAL_RECAP_API_KEY` secret. Kimi works the same way with its OpenAI-compatible base URL and model id. Other OpenAI-compatible providers use the same three settings.
+
 ## Secrets and variables
 
 Set these in your repository's **Settings → Secrets and variables → Actions**.
 
-### Secrets (only two required)
+### Secrets for the default backend
 
 | Secret              | Purpose                                                                                                                            |
 | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
@@ -190,8 +194,10 @@ real token.
 | Secret / variable        | Default                         | When you need it                                                                                                                                |
 | ------------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | `OPENAI_API_KEY`         | —                               | Secret. Set together with `VISUAL_RECAP_AGENT=codex` to run the recap with Codex instead.                                                       |
-| `VISUAL_RECAP_AGENT`     | `claude`                        | Variable. Selects the coding-agent backend (`claude` or `codex`).                                                                               |
-| `VISUAL_RECAP_MODEL`     | each CLI's default              | Variable. Pins the model — e.g. `gpt-5.6-sol` for Codex, or a Claude model id. Unset uses the CLI's own default.                                |
+| `VISUAL_RECAP_API_KEY`   | —                               | Secret. Set with `VISUAL_RECAP_AGENT=openai-compatible` for DeepSeek, Kimi, or another OpenAI-compatible provider.                              |
+| `VISUAL_RECAP_AGENT`     | `claude`                        | Variable. Selects the coding-agent backend (`claude`, `codex`, or `openai-compatible`).                                                         |
+| `VISUAL_RECAP_BASE_URL`  | required for compatible backend | Variable. HTTP(S) base URL for the OpenAI-compatible backend; credentials are rejected.                                                         |
+| `VISUAL_RECAP_MODEL`     | required for compatible backend | Variable. Provider model id for OpenAI-compatible backends; optional for Claude/Codex, where unset uses the CLI default.                        |
 | `VISUAL_RECAP_REASONING` | each model's default            | Variable. Reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Applies to the Codex backend.                                |
 | `RECAP_CLI_VERSION`      | `latest`                        | Variable. Pins the `@agent-native/core` CLI version the workflow installs — e.g. `1.5.0`. See [Version pinning](#version-pinning-copy-variant). |
 | `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com` | Secret. Only when self-hosting the Plans app at a different origin.                                                                             |
@@ -214,7 +220,7 @@ This also means you can merge the workflow file **before** the secrets exist: wi
 
 If you want to generate recaps for fork PRs, a second workflow file is available: `.github/workflows/pr-visual-recap-fork.yml`. It uses `pull_request_target` (which runs with base-repo secrets) but never checks out or executes fork code. Trusted fork authors with GitHub author association `OWNER`, `MEMBER`, or `COLLABORATOR` run automatically. Outside fork PRs require an explicit **per-head maintainer opt-in** via a fresh `recap` label event before the recap agent runs.
 
-To install it, copy the file from [BuilderIO/agent-native](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/pr-visual-recap-fork.yml) into your repo's `.github/workflows/` directory alongside the existing `pr-visual-recap.yml`. The same secrets (`PLAN_RECAP_TOKEN`, `ANTHROPIC_API_KEY`) apply.
+To install it, copy the file from [BuilderIO/agent-native](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/pr-visual-recap-fork.yml) into your repo's `.github/workflows/` directory alongside the existing `pr-visual-recap.yml`. The same backend configuration applies, including `VISUAL_RECAP_API_KEY`, `VISUAL_RECAP_BASE_URL`, and `VISUAL_RECAP_MODEL` when using an OpenAI-compatible provider.
 
 <Diagram id="doc-block-h3lne0" title="Fork PR consent gate" summary={"Fork PRs get no secrets by default; trusted authors run automatically, and outside contributors require a fresh maintainer recap label."}>
 
@@ -454,10 +460,12 @@ jobs:
       PLAN_RECAP_TOKEN: ${{ secrets.PLAN_RECAP_TOKEN }}
       ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      VISUAL_RECAP_API_KEY: ${{ secrets.VISUAL_RECAP_API_KEY }}
       PLAN_RECAP_APP_URL: ${{ secrets.PLAN_RECAP_APP_URL }}
     with:
       agent: ${{ vars.VISUAL_RECAP_AGENT || 'claude' }}
       model: ${{ vars.VISUAL_RECAP_MODEL || '' }}
+      base-url: ${{ vars.VISUAL_RECAP_BASE_URL || '' }}
       reasoning: ${{ vars.VISUAL_RECAP_REASONING || '' }}
       skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
       # cli-version: "latest"  # pin to a specific @agent-native/core version

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.94.2",
+  "version": "0.95.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/a2a/artifact-response.ts

@@ -228,6 +228,132 @@ function contentDatabaseSubmissionArtifact(
   };
 }
 
+function documentUrlForId(
+  parsed: Record<string, unknown>,
+  id: string,
+  additionalCandidates: Array<string | undefined> = [],
+  options: { requireContentOrigin?: boolean } = {},
+): string | undefined {
+  const candidates = [
+    stringValue(parsed.url),
+    stringValue(parsed.urlPath),
+    stringValue(parsed.deepLink),
+    stringValue(parsed.pageUrl),
+    stringValue(parsed.documentUrl),
+    ...additionalCandidates,
+  ].filter((value): value is string => !!value);
+
+  return candidates.find((candidate) => {
+    if (!artifactUrlReferencesId(candidate, "document", id)) return false;
+    return !options.requireContentOrigin || isContentDocumentUrl(candidate);
+  });
+}
+
+function isContentDocumentUrl(rawUrl: string): boolean {
+  try {
+    return new URL(rawUrl).origin === "https://content.agent-native.com";
+  } catch {
+    return false;
+  }
+}
+
+function addDocumentReadArtifact(
+  documents: Map<string, CreatedDocumentArtifact>,
+  parsed: Record<string, unknown>,
+  options: {
+    allowWithoutUrl: boolean;
+    additionalUrlCandidates?: Array<string | undefined>;
+    requireContentOrigin?: boolean;
+  },
+): void {
+  const id = stringValue(parsed.documentId) ?? stringValue(parsed.id);
+  if (!id) return;
+
+  const url = documentUrlForId(parsed, id, options.additionalUrlCandidates, {
+    requireContentOrigin: options.requireContentOrigin,
+  });
+  if (!url && !options.allowWithoutUrl) return;
+
+  documents.set(id, {
+    id,
+    title: stringValue(parsed.title) ?? stringValue(parsed.name),
+    url,
+  });
+}
+
+function addContentDatabaseReadArtifacts(
+  documents: Map<string, CreatedDocumentArtifact>,
+  parsed: Record<string, unknown>,
+): void {
+  const resultUrls = [
+    stringValue(parsed.url),
+    stringValue(parsed.urlPath),
+    stringValue(parsed.deepLink),
+  ];
+  const database = asRecord(parsed.database);
+  if (database) {
+    addDocumentReadArtifact(documents, database, {
+      allowWithoutUrl: true,
+      requireContentOrigin: true,
+      additionalUrlCandidates: resultUrls,
+    });
+  } else {
+    // Unavailable database reads still return a documentId, but they do not
+    // prove that the page exists and must not authorize an artifact URL.
+    if (parsed.available !== false) {
+      addDocumentReadArtifact(documents, parsed, {
+        allowWithoutUrl: true,
+        requireContentOrigin: true,
+      });
+    }
+  }
+
+  if (!Array.isArray(parsed.items)) return;
+  for (const item of parsed.items) {
+    const itemRecord = asRecord(item);
+    const document = asRecord(itemRecord?.document);
+    if (!document) continue;
+    addDocumentReadArtifact(documents, document, {
+      allowWithoutUrl: true,
+      requireContentOrigin: true,
+      additionalUrlCandidates: [
+        stringValue(itemRecord?.url),
+        stringValue(itemRecord?.urlPath),
+        stringValue(itemRecord?.deepLink),
+      ],
+    });
+  }
+}
+
+function isGenericReadTool(tool: string): boolean {
+  return /^(?:find|get|list|query|read|search)-/i.test(tool);
+}
+
+function addGenericDocumentReadArtifact(
+  documents: Map<string, CreatedDocumentArtifact>,
+  parsed: Record<string, unknown>,
+): void {
+  // Unknown read actions are accepted only when their result pairs a document
+  // ID with a canonical page URL containing that exact ID. An ID by itself is
+  // insufficient, preserving the fabrication guard for unrelated actions.
+  addDocumentReadArtifact(documents, parsed, {
+    allowWithoutUrl: false,
+    requireContentOrigin: true,
+  });
+
+  const document = asRecord(parsed.document);
+  if (!document) return;
+  addDocumentReadArtifact(documents, document, {
+    allowWithoutUrl: false,
+    requireContentOrigin: true,
+    additionalUrlCandidates: [
+      stringValue(parsed.url),
+      stringValue(parsed.urlPath),
+      stringValue(parsed.deepLink),
+    ],
+  });
+}
+
 function addImageArtifact(
   images: Map<string, CreatedImageArtifact>,
   parsed: Record<string, unknown>,
@@ -387,7 +513,6 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
 
     if (
       toolResult.tool === "create-document" ||
-      toolResult.tool === "get-document" ||
       toolResult.tool === "update-document"
     ) {
       const id = stringValue(parsed.id);
@@ -401,6 +526,34 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
       continue;
     }
 
+    if (
+      toolResult.tool === "get-document" ||
+      toolResult.tool === "get-content-document"
+    ) {
+      const document = asRecord(parsed.document);
+      addDocumentReadArtifact(documents, document ?? parsed, {
+        allowWithoutUrl: true,
+        requireContentOrigin: true,
+        additionalUrlCandidates: document
+          ? [
+              stringValue(parsed.url),
+              stringValue(parsed.urlPath),
+              stringValue(parsed.deepLink),
+            ]
+          : [],
+      });
+      continue;
+    }
+
+    if (toolResult.tool === "get-content-database") {
+      addContentDatabaseReadArtifacts(documents, parsed);
+      continue;
+    }
+
+    if (isGenericReadTool(toolResult.tool)) {
+      addGenericDocumentReadArtifact(documents, parsed);
+    }
+
     if (
       toolResult.tool === "create-deck" ||
       toolResult.tool === "duplicate-deck"

package/corpus/core/src/agent/engine/ai-sdk-engine.ts

@@ -205,6 +205,7 @@ class AISDKEngine implements AgentEngine {
   readonly label: string;
   readonly defaultModel: string;
   readonly supportedModels: readonly string[];
+  readonly preserveCustomModels: boolean;
   readonly capabilities: EngineCapabilities;
 
   private readonly provider: AISDKProvider;
@@ -219,6 +220,8 @@ class AISDKEngine implements AgentEngine {
     this.label = `${capitalize(provider)} (AI SDK)`;
     this.defaultModel = config.model ?? PROVIDER_DEFAULT_MODELS[provider];
     this.supportedModels = PROVIDER_SUPPORTED_MODELS[provider];
+    this.preserveCustomModels =
+      provider === "openai" && Boolean(config.baseUrl);
     this.capabilities = PROVIDER_CAPABILITIES[provider];
     this.apiKey =
       config.apiKey ??

package/corpus/core/src/agent/engine/registry.ts

@@ -180,12 +180,17 @@ function findLatestSupportedVersionMatch(
 }
 
 export function normalizeModelForEngine(
-  engine: Pick<AgentEngine, "name" | "defaultModel" | "supportedModels">,
+  engine: Pick<
+    AgentEngine,
+    "name" | "defaultModel" | "supportedModels" | "preserveCustomModels"
+  >,
   model: string | null | undefined,
 ): string {
   const candidate = typeof model === "string" ? model.trim() : "";
   if (!candidate) return engine.defaultModel;
 
+  if (engine.preserveCustomModels) return candidate;
+
   if (engine.supportedModels.length === 0) return candidate;
 
   if (candidate === "auto" || engine.supportedModels.includes(candidate)) {

package/corpus/core/src/agent/engine/types.ts

@@ -297,6 +297,8 @@ export interface AgentEngine {
   readonly defaultModel: string;
   /** Models this engine supports */
   readonly supportedModels: readonly string[];
+  /** Whether the configured endpoint accepts provider-defined model ids. */
+  readonly preserveCustomModels?: boolean;
   /** Capability flags used to gate provider-specific features */
   readonly capabilities: EngineCapabilities;
 

package/corpus/core/src/cli/code-agent-executor.ts

@@ -101,6 +101,10 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const MAX_TOOL_OUTPUT_CHARS = 50_000;
 const MAX_FILE_READ_CHARS = 120_000;
 const CODEX_CLI_ENGINE_NAME = "codex-cli";
+const RECAP_SOURCE_TOOL_PROFILE = "recap-source";
+const RECAP_SOURCE_OUTPUT_FILE = "recap-source.json";
+
+type CodeAgentToolProfile = typeof RECAP_SOURCE_TOOL_PROFILE;
 
 /**
  * Number of most-recent transcript events reconstructed as native
@@ -237,6 +241,9 @@ export async function executeCodeAgentRun(
     options.reasoningEffort ?? metadataReasoningEffort(existing);
   const cwd = existing.cwd || process.cwd();
   const permissionMode = existing.permissionMode ?? "full-auto";
+  const toolProfile = resolveCodeAgentToolProfile(
+    process.env.AGENT_NATIVE_CODE_TOOL_PROFILE,
+  );
 
   // Holds structured metadata emitted by the coding tools side-channel.
   // Keyed by tool name; consumed when the matching tool_start / tool_done fires.
@@ -254,8 +261,11 @@ export async function executeCodeAgentRun(
       // Stream incremental bash output to stdout for the terminal smoother
       options.stdout?.write(chunk);
     },
+    toolProfile,
   );
-  const mcpManager = await startCodeAgentMcpManager(existing.id);
+  const mcpManager = toolProfile
+    ? null
+    : await startCodeAgentMcpManager(existing.id);
   if (mcpManager) {
     Object.assign(
       actions,
@@ -392,6 +402,7 @@ export async function executeCodeAgentRun(
         }),
     );
     loopUsage = usageResult ?? null;
+    writeCodeAgentUsageSnapshot(cwd, loopUsage);
     // Persist cumulative token totals from this turn into the run record so
     // the UI can display per-run usage statistics.
     if (loopUsage) {
@@ -1663,6 +1674,7 @@ function createLocalCodeAgentActions(
     meta: StructuredToolMetadata,
   ) => void,
   onBashOutputChunk?: (chunk: string) => void,
+  toolProfile?: CodeAgentToolProfile,
 ): Record<string, ActionEntry> {
   const actions = createCodingToolRegistry({
     cwd,
@@ -1701,6 +1713,24 @@ function createLocalCodeAgentActions(
       return null;
     },
   });
+  if (toolProfile === RECAP_SOURCE_TOOL_PROFILE) {
+    const allowedOutput = path.resolve(cwd, RECAP_SOURCE_OUTPUT_FILE);
+    const writeAction = actions.write;
+    return {
+      read: actions.read,
+      write: {
+        ...writeAction,
+        run: async (args, context) => {
+          const requestedPath =
+            args && typeof args.path === "string" ? args.path : "";
+          if (path.resolve(cwd, requestedPath) !== allowedOutput) {
+            return `Error: only ${RECAP_SOURCE_OUTPUT_FILE} may be written in the recap-source tool profile.`;
+          }
+          return writeAction.run(args, context);
+        },
+      },
+    };
+  }
   if (permissionMode === "read-only") {
     return {
       bash: actions.bash,
@@ -1710,6 +1740,15 @@ function createLocalCodeAgentActions(
   return actions;
 }
 
+function resolveCodeAgentToolProfile(
+  value: string | undefined,
+): CodeAgentToolProfile | undefined {
+  const normalized = value?.trim();
+  if (!normalized) return undefined;
+  if (normalized === RECAP_SOURCE_TOOL_PROFILE) return normalized;
+  throw new Error(`Unsupported Agent-Native Code tool profile: ${normalized}`);
+}
+
 export type CodeAgentCommandPermission =
   | { kind: "read" }
   | { kind: "write" }
@@ -1863,6 +1902,27 @@ function getPendingApproval(runId: string): PendingCodeAgentApproval | null {
   };
 }
 
+export function writeCodeAgentUsageSnapshot(
+  cwd: string,
+  usage: AgentLoopUsage | null,
+): void {
+  const configuredPath = process.env.AGENT_NATIVE_CODE_USAGE_FILE?.trim();
+  if (!configuredPath || !usage) return;
+
+  const outputPath = path.isAbsolute(configuredPath)
+    ? configuredPath
+    : path.resolve(cwd, configuredPath);
+  try {
+    fs.writeFileSync(outputPath, `${JSON.stringify(usage)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+  } catch {
+    // Usage reporting is best-effort and must not turn a completed agent run
+    // into a failed recap when the optional sidecar cannot be written.
+  }
+}
+
 // --------------- Token usage accumulator ---------------
 
 interface StoredTokenUsage {