@agent-native/core 0.99.3 → 0.100.0

package/corpus/core/docs/content/locales/zh-TW/agent-surfaces.mdx

@@ -6,6 +6,35 @@ search: "無頭代理豐富聊天完整應用程式 BYO 代理執行時 AgentCha
 
 # 代理表面
 
+## 完整的 Agent 工作區 {#agent-page}
+
+當完整應用程式需要一個持久位置來檢查和設定代理時，請在 `/agent` 掛載
+`AgentTabsPage`。將此路由加入應用程式導覽，並向 `AgentSidebar` 傳入
+`agentPageHref="/agent"`，這樣 Resources 和 Settings 模式就能連結到完整頁面，
+而不必重複這些流程。
+
+```tsx filename="app/routes/agent.tsx"
+import { AgentTabsPage } from "@agent-native/core/client";
+
+export default function AgentRoute() {
+  return <AgentTabsPage />;
+}
+```
+
+共用頁面目前提供五個分頁：
+
+- **Context** — 顯示範圍預覽、權杖預算、按來源/治理/來源參照分組的有序系統區段、清單/treemap 檢視和最新即時執行緒快照。
+- **Files** — 為個人或組織資源重新託管現有的 `ResourcesPanel`。
+- **Connections** — MCP 伺服器管理和 A2A 遠端代理清單，也就是此應用程式的代理可以呼叫什麼。
+- **Jobs** — 使用現有暫停/恢復、詳細資料和刪除流程的範圍化定期工作與自動化。自動化目前僅限個人。
+- **Access** — MCP URL、可用時的 A2A 代理卡片以及共用用戶端設定指南；完整連線流程和權杖備援位於 `/mcp/connect`。
+
+頁面級 **Personal / Organization** 切換器為分頁提供範圍。成員可以檢查組織
+資料；在託管元件實施該界線的地方，組織管理仍僅限擁有者/管理員。目標是讓內容可
+檢查、可歸因、可治理，並將能力與存取分開。此頁面只是對現有元件、動作和
+存取檢查的薄封裝，不是新的管理主控台。目前還沒有 grants、範圍編輯、撤銷
+介面或逐次迭代的 provenance 歷史。
+
 Agent-Native 是故意可組合的。不用太多就可以使用代理 UI，
 在沒有內建代理執行時的情況下使用 UI，或者將兩者一起用作完整的
 應用程式。

package/corpus/core/docs/content/locales/zh-TW/external-agents.mdx

@@ -117,6 +117,14 @@ https://<your-app>.agent-native.com/mcp
 `https://&lt;app&gt;/mcp/connect` 與可複製的 URL 和
 Claude、ChatGPT、游標、Claude 程式碼、Codex 和其他的主機特定分頁。
 
+### 應用程式內的 Access 分頁 {#access-tab}
+
+掛載 `AgentTabsPage` 的應用程式也會在 **Access** 分頁提供相同的連線流程。
+它會顯示 MCP URL、可用時的 A2A 代理卡片，以及 Claude、ChatGPT、Cursor、Claude
+Code、Codex 和其他用戶端的共用設定指南。可將它作為應用程式內的起點，並開啟
+`/mcp/connect` 查看完整流程和權杖備援。這是連線設定介面，不是通用存取控制台；
+此分頁目前還不管理 grants、範圍編輯或撤銷。
+
 ### Claude 和 ChatGPT OAuth {#oauth}
 
 Claude / Claude 桌面：新增自訂連線器，貼上 MCP URL，點選

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.99.3",
+  "version": "0.100.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/agent/context-xray/actions/context-evict.ts

@@ -7,12 +7,15 @@ import {
 } from "../../../server/request-context.js";
 import { callerOwnsThread } from "../../run-ownership.js";
 import {
+  readContextManifest,
   upsertContextDirective,
   writeContextManifestStatus,
 } from "../directives-store.js";
 import {
   contextXrayAuthError,
+  contextXraySystemSegmentError,
   contextXrayThreadNotFoundError,
+  isContextXraySystemSegment,
 } from "./errors.js";
 
 export default defineAction({
@@ -28,6 +31,14 @@ export default defineAction({
     if (!(await callerOwnsThread(ownerEmail, args.threadId))) {
       throw contextXrayThreadNotFoundError();
     }
+    if (
+      isContextXraySystemSegment(
+        await readContextManifest(args.threadId),
+        args.segmentId,
+      )
+    ) {
+      throw contextXraySystemSegmentError();
+    }
     const directive = await upsertContextDirective({
       threadId: args.threadId,
       segmentId: args.segmentId,

package/corpus/core/src/agent/context-xray/actions/context-pin.ts

@@ -7,12 +7,15 @@ import {
 } from "../../../server/request-context.js";
 import { callerOwnsThread } from "../../run-ownership.js";
 import {
+  readContextManifest,
   upsertContextDirective,
   writeContextManifestStatus,
 } from "../directives-store.js";
 import {
   contextXrayAuthError,
+  contextXraySystemSegmentError,
   contextXrayThreadNotFoundError,
+  isContextXraySystemSegment,
 } from "./errors.js";
 
 export default defineAction({
@@ -28,6 +31,14 @@ export default defineAction({
     if (!(await callerOwnsThread(ownerEmail, args.threadId))) {
       throw contextXrayThreadNotFoundError();
     }
+    if (
+      isContextXraySystemSegment(
+        await readContextManifest(args.threadId),
+        args.segmentId,
+      )
+    ) {
+      throw contextXraySystemSegmentError();
+    }
     const directive = await upsertContextDirective({
       threadId: args.threadId,
       segmentId: args.segmentId,

package/corpus/core/src/agent/context-xray/actions/context-preview-get.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+
+import { defineAction } from "../../../action.js";
+import { embedApp } from "../../../mcp/embed-app.js";
+import { SHARED_OWNER } from "../../../resources/store.js";
+import {
+  buildFrameworkPrompts,
+  buildSchemaBlock,
+} from "../../../server/agent-chat/framework-prompts.js";
+import {
+  loadResourcesForPrompt,
+  promptResourceManifestSections,
+} from "../../../server/agent-chat/prompt-resources.js";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "../../../server/request-context.js";
+import {
+  type ContextPreview,
+  type ContextTokenCountMethod,
+} from "../../../shared/context-xray.js";
+import { buildSystemManifestSections } from "../manifest.js";
+import { contextXrayAuthError } from "./errors.js";
+
+function combineMethods(
+  left: ContextTokenCountMethod,
+  right: ContextTokenCountMethod,
+): ContextTokenCountMethod {
+  return left === "estimate" || right === "estimate" ? "estimate" : "exact";
+}
+
+export async function buildContextPreview(input: {
+  ownerEmail: string;
+  orgId?: string | null;
+  scope: "user" | "org";
+  appId?: string;
+  compact?: boolean;
+  model?: string;
+}): Promise<ContextPreview> {
+  const compact = input.compact ?? false;
+  const prompts = buildFrameworkPrompts();
+  const resources = await loadResourcesForPrompt(
+    input.scope === "org" ? SHARED_OWNER : input.ownerEmail,
+    compact,
+    input.appId,
+    input.orgId ?? null,
+  );
+  const schemaBlock = compact
+    ? ""
+    : await buildSchemaBlock(input.ownerEmail, "read");
+  const sections = await buildSystemManifestSections([
+    {
+      label: "Framework core",
+      provenance: "framework-core",
+      governance: "required",
+      content: compact
+        ? prompts.PROD_FRAMEWORK_PROMPT_COMPACT
+        : prompts.PROD_FRAMEWORK_PROMPT,
+      sourceRef: { scope: "framework" },
+    },
+    ...promptResourceManifestSections(resources),
+    ...(schemaBlock
+      ? [
+          {
+            label: "SQL schema",
+            provenance: "db-schema" as const,
+            governance: "required" as const,
+            content: schemaBlock,
+            sourceRef: { scope: "sql" },
+          },
+        ]
+      : []),
+  ]);
+  const systemTokens = sections.reduce(
+    (total, section) => total + section.tokenCount,
+    0,
+  );
+  const tokenCountMethod = sections.reduce(
+    (method, section) => combineMethods(method, section.tokenMethod),
+    "exact" as ContextTokenCountMethod,
+  );
+  return {
+    computedAt: Date.now(),
+    ...(input.model ? { model: input.model } : {}),
+    scope: input.scope,
+    totalTokens: systemTokens,
+    systemTokens,
+    tokenCountMethod,
+    sections,
+    source: "preview",
+  };
+}
+
+export default defineAction({
+  description:
+    "Preview the system-prompt context that would be composed for the current user, organization, and app without a live chat thread.",
+  schema: z.object({
+    scope: z
+      .enum(["user", "org"])
+      .default("user")
+      .describe(
+        "Configuration scope to preview: user includes personal context; org includes inherited organization context.",
+      ),
+    appId: z.string().optional().describe("Current app id, when available."),
+    compact: z.boolean().optional().describe("Use the compact startup prompt."),
+    model: z.string().optional().describe("Model id for display metadata."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Context preview",
+      description:
+        "Preview the system-prompt context before starting a thread.",
+      iframeTitle: "Context preview",
+      openLabel: "Open context preview",
+      height: 720,
+    }),
+  },
+  run: async (args): Promise<ContextPreview> => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw contextXrayAuthError();
+    return await buildContextPreview({
+      ownerEmail,
+      orgId: getRequestOrgId() ?? null,
+      scope: args.scope,
+      ...(args.appId ? { appId: args.appId } : {}),
+      ...(args.compact !== undefined ? { compact: args.compact } : {}),
+      ...(args.model ? { model: args.model } : {}),
+    });
+  },
+});

package/corpus/core/src/agent/context-xray/actions/context-restore.ts

@@ -5,11 +5,14 @@ import { getRequestUserEmail } from "../../../server/request-context.js";
 import { callerOwnsThread } from "../../run-ownership.js";
 import {
   deactivateContextDirective,
+  readContextManifest,
   writeContextManifestStatus,
 } from "../directives-store.js";
 import {
   contextXrayAuthError,
+  contextXraySystemSegmentError,
   contextXrayThreadNotFoundError,
+  isContextXraySystemSegment,
 } from "./errors.js";
 
 export default defineAction({
@@ -25,6 +28,14 @@ export default defineAction({
     if (!(await callerOwnsThread(ownerEmail, args.threadId))) {
       throw contextXrayThreadNotFoundError();
     }
+    if (
+      isContextXraySystemSegment(
+        await readContextManifest(args.threadId),
+        args.segmentId,
+      )
+    ) {
+      throw contextXraySystemSegmentError();
+    }
     const restored = await deactivateContextDirective({
       threadId: args.threadId,
       segmentId: args.segmentId,

package/corpus/core/src/agent/context-xray/actions/errors.ts

@@ -1,3 +1,5 @@
+import type { ContextManifest } from "../../../shared/context-xray.js";
+
 export class ContextXrayActionError extends Error {
   constructor(
     message: string,
@@ -18,3 +20,21 @@ export function contextXrayAuthError(): ContextXrayActionError {
 export function contextXrayThreadNotFoundError(): ContextXrayActionError {
   return new ContextXrayActionError("Thread not found.", 404);
 }
+
+export function contextXraySystemSegmentError(): ContextXrayActionError {
+  return new ContextXrayActionError(
+    "System Context X-Ray sections are required and cannot be pinned, evicted, or restored.",
+    400,
+  );
+}
+
+export function isContextXraySystemSegment(
+  manifest: ContextManifest | null,
+  segmentId: string,
+): boolean {
+  return (
+    manifest?.systemSections?.some(
+      (section) => section.segmentId === segmentId,
+    ) ?? false
+  );
+}

package/corpus/core/src/agent/context-xray/manifest.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 import { appStatePut } from "../../application-state/store.js";
 import { buildDeepLink } from "../../server/deep-link.js";
 import {
@@ -5,9 +7,13 @@ import {
   type ContextDirective,
   type ContextManifest,
   type ContextManifestSegment,
+  type ContextManifestSourceRef,
+  type ContextManifestSystemSection,
   type ContextManifestSource,
   type ContextSegmentStatus,
   type ContextTokenCountMethod,
+  type ContextGovernanceTier,
+  type ContextSystemProvenance,
 } from "../../shared/context-xray.js";
 import type { EngineMessage } from "../engine/types.js";
 import { computeSegments } from "./segments.js";
@@ -19,6 +25,85 @@ import {
 
 export { CONTEXT_XRAY_MANIFEST_KEY };
 
+export const CONTEXT_XRAY_REQUEST_SECTIONS_KEY =
+  "__agentNativeContextXraySystemSections";
+
+export interface SystemManifestSectionInput {
+  label: string;
+  provenance: ContextSystemProvenance;
+  governance: ContextGovernanceTier;
+  content: string;
+  group?: string;
+  sourceRef?: ContextManifestSourceRef;
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function previewText(value: string): string {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (normalized.length <= 200) return normalized;
+  return `${normalized.slice(0, 197)}...`;
+}
+
+export async function buildSystemManifestSections(
+  inputs: SystemManifestSectionInput[],
+): Promise<ContextManifestSystemSection[]> {
+  const timestamp = Date.now();
+  return await Promise.all(
+    inputs
+      .filter((input) => input.content.trim().length > 0)
+      .map(async (input, index) => {
+        const content = input.content.trim();
+        const count = await countTextTokens(content);
+        const identity = [
+          input.provenance,
+          input.label,
+          input.sourceRef?.resourceId ?? "",
+          input.sourceRef?.path ?? "",
+          content,
+          index,
+        ].join("\u0000");
+        return {
+          kind: "system" as const,
+          segmentId: `system:${sha256(identity).slice(0, 16)}`,
+          group: input.group ?? "System",
+          label: input.label,
+          provenance: input.provenance,
+          governance: input.governance,
+          tokenCount: count.tokens,
+          tokenMethod: count.method,
+          ...(input.sourceRef ? { sourceRef: input.sourceRef } : {}),
+          contentHash: sha256(content),
+          preview: previewText(content),
+          timestamp,
+        } satisfies ContextManifestSystemSection;
+      }),
+  );
+}
+
+type ContextXRayEvent = {
+  context?: Record<string, unknown>;
+};
+
+export function setContextXraySystemSections(
+  event: ContextXRayEvent,
+  sections: ContextManifestSystemSection[],
+): void {
+  event.context = event.context ?? {};
+  event.context[CONTEXT_XRAY_REQUEST_SECTIONS_KEY] = sections;
+}
+
+export function readContextXraySystemSections(
+  event: ContextXRayEvent,
+): ContextManifestSystemSection[] {
+  const sections = event.context?.[CONTEXT_XRAY_REQUEST_SECTIONS_KEY];
+  return Array.isArray(sections)
+    ? (sections as ContextManifestSystemSection[])
+    : [];
+}
+
 export interface BuildManifestInput {
   threadId: string;
   turnId?: string;
@@ -30,6 +115,7 @@ export interface BuildManifestInput {
   protectedSegmentIds?: Set<string>;
   source?: ContextManifestSource;
   enforceable?: boolean;
+  systemSections?: ContextManifestSystemSection[];
 }
 
 function combineMethods(
@@ -62,7 +148,7 @@ async function summaryTokenCount(
   return (await countTextTokens(text)).tokens;
 }
 
-function contextXrayUrl(threadId: string): string {
+export function contextXrayDeepLink(threadId: string): string {
   const to = `/?contextXray=1&threadId=${encodeURIComponent(threadId)}`;
   return buildDeepLink({
     app: "agent-native",
@@ -119,8 +205,18 @@ export async function buildManifest(
     });
   }
 
-  const totalTokens = sentTokenTotals.tokens;
-  const rawTokens = rawTokenTotals.tokens;
+  const systemSections = input.systemSections ?? [];
+  const systemTokenTotals = systemSections.reduce(
+    (acc, section) => ({
+      tokens: acc.tokens + section.tokenCount,
+      method: combineMethods(acc.method, section.tokenMethod),
+    }),
+    { tokens: 0, method: "exact" as ContextTokenCountMethod },
+  );
+  const conversationTokens = sentTokenTotals.tokens;
+  const rawConversationTokens = rawTokenTotals.tokens;
+  const totalTokens = systemTokenTotals.tokens + conversationTokens;
+  const rawTokens = systemTokenTotals.tokens + rawConversationTokens;
   return {
     threadId: input.threadId,
     ...(input.turnId ? { turnId: input.turnId } : {}),
@@ -128,15 +224,18 @@ export async function buildManifest(
     ...(input.model ? { model: input.model } : {}),
     totalTokens,
     rawTokens,
-    reclaimedTokens: Math.max(0, rawTokens - totalTokens),
+    reclaimedTokens: Math.max(0, rawConversationTokens - conversationTokens),
     tokenCountMethod: combineMethods(
-      rawTokenTotals.method,
-      sentTokenTotals.method,
+      combineMethods(rawTokenTotals.method, sentTokenTotals.method),
+      systemTokenTotals.method,
     ),
+    conversationTokens,
+    systemTokens: systemTokenTotals.tokens,
     source: input.source ?? "structured",
     enforceable: input.enforceable ?? true,
     segments,
-    url: contextXrayUrl(input.threadId),
+    ...(systemSections.length > 0 ? { systemSections } : {}),
+    url: contextXrayDeepLink(input.threadId),
   };
 }
 

package/corpus/core/src/agent/engine/context-directives-transform.ts

@@ -1,3 +1,4 @@
+import type { ContextManifestSystemSection } from "../../shared/context-xray.js";
 import { applyContextDirectives } from "../context-xray/apply-directives.js";
 import { loadContextDirectives } from "../context-xray/directives-store.js";
 import {
@@ -29,8 +30,10 @@ export async function applyContextXrayTransformForIteration(opts: {
   turnId?: string;
   model: string;
   messages: EngineMessage[];
+  systemSections?: ContextManifestSystemSection[];
 }): Promise<EngineMessage[]> {
-  const { threadId, ownerEmail, turnId, model, messages } = opts;
+  const { threadId, ownerEmail, turnId, model, messages, systemSections } =
+    opts;
   try {
     const directives = await loadContextDirectives(threadId, {
       ownerEmail: ownerEmail ?? null,
@@ -49,6 +52,7 @@ export async function applyContextXrayTransformForIteration(opts: {
       appliedStatus,
       directives,
       protectedSegmentIds,
+      ...(systemSections ? { systemSections } : {}),
       source: "structured",
       enforceable: true,
     });