@agent-native/core 0.113.0 → 0.114.1

package/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/src/agent/context-xray/actions/context-report.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+
+import { defineAction } from "../../../action.js";
+import { appStatePut } from "../../../application-state/store.js";
+import { getRequestUserEmail } from "../../../server/request-context.js";
+import {
+  CONTEXT_XRAY_MANIFEST_KEY,
+  type ContextManifest,
+} from "../../../shared/context-xray.js";
+import { callerOwnsThread } from "../../run-ownership.js";
+import {
+  contextXrayAuthError,
+  contextXrayThreadNotFoundError,
+} from "./errors.js";
+
+const reportedSegmentSchema = z.object({
+  segmentId: z.string(),
+  label: z.string(),
+  tokenCount: z.number().int().nonnegative(),
+  group: z.string().default("External context"),
+  status: z
+    .enum(["active", "pinned", "evicted", "summarized"])
+    .default("active"),
+});
+
+export default defineAction({
+  description:
+    "Report an external agent host's visible context segments to Context X-Ray. External reports are advisory unless the content came from Agent-Native.",
+  schema: z.object({
+    threadId: z.string(),
+    model: z.string().optional(),
+    segments: z.array(reportedSegmentSchema).default([]),
+  }),
+  run: async (args): Promise<ContextManifest> => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw contextXrayAuthError();
+    if (!(await callerOwnsThread(ownerEmail, args.threadId))) {
+      throw contextXrayThreadNotFoundError();
+    }
+    const rawTokens = args.segments.reduce(
+      (sum, segment) => sum + segment.tokenCount,
+      0,
+    );
+    const manifest: ContextManifest = {
+      threadId: args.threadId,
+      computedAt: Date.now(),
+      ...(args.model ? { model: args.model } : {}),
+      totalTokens: rawTokens,
+      rawTokens,
+      reclaimedTokens: 0,
+      tokenCountMethod: "estimate",
+      source: "external",
+      enforceable: false,
+      segments: args.segments.map((segment) => ({
+        segmentId: segment.segmentId,
+        type: "text",
+        role: "user",
+        group: segment.group,
+        label: segment.label,
+        tokenCount: segment.tokenCount,
+        tokenMethod: "estimate",
+        status: segment.status,
+      })),
+    };
+    await appStatePut(
+      args.threadId,
+      CONTEXT_XRAY_MANIFEST_KEY,
+      manifest as unknown as Record<string, unknown>,
+      {
+        requestSource: "context-xray",
+      },
+    );
+    return manifest;
+  },
+});

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

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+import { defineAction } from "../../../action.js";
+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({
+  description:
+    "Restore a Context X-Ray segment by deactivating its pin, evict, or summarize directive.",
+  schema: z.object({
+    threadId: z.string(),
+    segmentId: z.string(),
+  }),
+  run: async (args) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw contextXrayAuthError();
+    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,
+      ownerEmail,
+    });
+    const manifest = await writeContextManifestStatus({
+      threadId: args.threadId,
+      segmentId: args.segmentId,
+      status: "active",
+    });
+    return { restored, manifest };
+  },
+});

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

@@ -0,0 +1,40 @@
+import type { ContextManifest } from "../../../shared/context-xray.js";
+
+export class ContextXrayActionError extends Error {
+  constructor(
+    message: string,
+    readonly statusCode: number,
+  ) {
+    super(message);
+    this.name = "ContextXrayActionError";
+  }
+}
+
+export function contextXrayAuthError(): ContextXrayActionError {
+  return new ContextXrayActionError(
+    "Context X-Ray requires a signed-in user.",
+    401,
+  );
+}
+
+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/src/agent/context-xray/apply-directives.ts

@@ -0,0 +1,137 @@
+import type {
+  ContextDirective,
+  ContextSegmentStatus,
+} from "../../shared/context-xray.js";
+import type { EngineContentPart, EngineMessage } from "../engine/types.js";
+import { computeSegments } from "./segments.js";
+
+export interface ApplyContextDirectivesResult {
+  messages: EngineMessage[];
+  appliedStatus: Map<string, ContextSegmentStatus>;
+}
+
+type PlannedTransform = "evict" | "summarize";
+
+function clonePart(part: EngineContentPart): EngineContentPart {
+  return { ...(part as any) } as EngineContentPart;
+}
+
+function plannedTransformForDirective(
+  directive: ContextDirective | undefined,
+): PlannedTransform | null {
+  if (!directive?.active) return null;
+  if (directive.action === "evict") return "evict";
+  if (directive.action === "summarize") return "summarize";
+  return null;
+}
+
+function statusForTransform(transform: PlannedTransform): ContextSegmentStatus {
+  return transform === "evict" ? "evicted" : "summarized";
+}
+
+function summaryTextFor(
+  directive: ContextDirective | undefined,
+  fallbackLabel: string,
+): string {
+  const summary = directive?.summaryText?.trim();
+  return summary || `${fallbackLabel} was summarized to reduce context size.`;
+}
+
+function appendTransformedMessage(
+  output: EngineMessage[],
+  message: EngineMessage,
+  content: EngineContentPart[],
+): void {
+  if (content.length === 0) return;
+  const previous = output.at(-1);
+  if (previous?.role === message.role) {
+    previous.content.push(...content);
+    return;
+  }
+  output.push({ ...message, content });
+}
+
+export function applyContextDirectives(
+  messages: EngineMessage[],
+  directives: Map<string, ContextDirective>,
+  opts: { protectedSegmentIds: Set<string> },
+): ApplyContextDirectivesResult {
+  const segments = computeSegments(messages);
+  const byPosition = new Map(
+    segments.map((segment) => [
+      `${segment.msgIndex}:${segment.partIndex}`,
+      segment,
+    ]),
+  );
+  const pairMembers = new Map<string, string[]>();
+  for (const segment of segments) {
+    if (!segment.pairKey) continue;
+    const members = pairMembers.get(segment.pairKey) ?? [];
+    members.push(segment.segmentId);
+    pairMembers.set(segment.pairKey, members);
+  }
+
+  const transformById = new Map<string, PlannedTransform>();
+  const appliedStatus = new Map<string, ContextSegmentStatus>();
+
+  for (const segment of segments) {
+    const directive = directives.get(segment.segmentId);
+    if (!directive?.active) continue;
+
+    if (directive.action === "pin") {
+      appliedStatus.set(segment.segmentId, "pinned");
+      continue;
+    }
+
+    const transform = plannedTransformForDirective(directive);
+    if (!transform) continue;
+    const ids = segment.pairKey
+      ? (pairMembers.get(segment.pairKey) ?? [segment.segmentId])
+      : [segment.segmentId];
+    const hasProtectedMember = ids.some((id) =>
+      opts.protectedSegmentIds.has(id),
+    );
+    if (hasProtectedMember) continue;
+    for (const id of ids) transformById.set(id, transform);
+  }
+
+  const output: EngineMessage[] = [];
+  for (const [msgIndex, message] of messages.entries()) {
+    const nextParts: EngineContentPart[] = [];
+    for (const [partIndex, part] of message.content.entries()) {
+      const actualSegment = byPosition.get(`${msgIndex}:${partIndex}`);
+      if (!actualSegment) {
+        nextParts.push(clonePart(part));
+        continue;
+      }
+      if (opts.protectedSegmentIds.has(actualSegment.segmentId)) {
+        nextParts.push(clonePart(part));
+        continue;
+      }
+      const transform = transformById.get(actualSegment.segmentId);
+      if (transform === "evict") {
+        appliedStatus.set(
+          actualSegment.segmentId,
+          statusForTransform(transform),
+        );
+        continue;
+      }
+      if (transform === "summarize") {
+        const directive = directives.get(actualSegment.segmentId);
+        nextParts.push({
+          type: "text",
+          text: `[summarized] ${summaryTextFor(directive, actualSegment.label)}`,
+        });
+        appliedStatus.set(
+          actualSegment.segmentId,
+          statusForTransform(transform),
+        );
+        continue;
+      }
+      nextParts.push(clonePart(part));
+    }
+    appendTransformedMessage(output, message, nextParts);
+  }
+
+  return { messages: output, appliedStatus };
+}

package/src/agent/context-xray/directives-store.ts

@@ -0,0 +1,178 @@
+import { appStateGet, appStatePut } from "../../application-state/store.js";
+import { getDbExec } from "../../db/client.js";
+import {
+  CONTEXT_XRAY_MANIFEST_KEY,
+  type ContextDirective,
+  type ContextDirectiveAction,
+  type ContextDirectiveCreator,
+  type ContextManifest,
+} from "../../shared/context-xray.js";
+import { updateManifestSegmentStatus } from "./manifest.js";
+
+function directiveId(): string {
+  return `ctxdir-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function rowBool(value: unknown): boolean {
+  return value === true || value === 1 || value === "1";
+}
+
+function rowToDirective(row: Record<string, unknown>): ContextDirective {
+  return {
+    id: String(row.id),
+    threadId: String(row.thread_id),
+    segmentId: String(row.segment_id),
+    action: row.action as ContextDirectiveAction,
+    summaryText: typeof row.summary_text === "string" ? row.summary_text : null,
+    createdBy: row.created_by as ContextDirectiveCreator,
+    active: rowBool(row.active),
+    originTurn: typeof row.origin_turn === "string" ? row.origin_turn : null,
+    createdAt: Number(row.created_at) || undefined,
+    updatedAt: Number(row.updated_at) || undefined,
+  };
+}
+
+export async function loadContextDirectives(
+  threadId: string,
+  opts: { ownerEmail?: string | null } = {},
+): Promise<Map<string, ContextDirective>> {
+  const client = getDbExec();
+  const ownerClause = opts.ownerEmail ? " AND owner_email = ?" : "";
+  const args: unknown[] = [threadId, 1];
+  if (opts.ownerEmail) args.push(opts.ownerEmail);
+  const result = await client.execute({
+    sql: `SELECT * FROM context_directives WHERE thread_id = ? AND active = ?${ownerClause} ORDER BY updated_at ASC`,
+    args,
+  });
+  const out = new Map<string, ContextDirective>();
+  for (const row of result.rows as Record<string, unknown>[]) {
+    const directive = rowToDirective(row);
+    out.set(directive.segmentId, directive);
+  }
+  return out;
+}
+
+export async function upsertContextDirective(input: {
+  threadId: string;
+  segmentId: string;
+  action: ContextDirectiveAction;
+  summaryText?: string | null;
+  createdBy?: ContextDirectiveCreator;
+  originTurn?: string | null;
+  ownerEmail: string;
+  orgId?: string | null;
+}): Promise<ContextDirective> {
+  const client = getDbExec();
+  const now = Date.now();
+  const existing = await client.execute({
+    sql: `SELECT * FROM context_directives WHERE thread_id = ? AND segment_id = ? AND owner_email = ? ORDER BY updated_at DESC LIMIT 1`,
+    args: [input.threadId, input.segmentId, input.ownerEmail],
+  });
+  const row = (existing.rows as Record<string, unknown>[])[0];
+  if (row) {
+    await client.execute({
+      sql: `UPDATE context_directives
+        SET action = ?, summary_text = ?, created_by = ?, active = ?, origin_turn = ?, updated_at = ?, org_id = COALESCE(?, org_id)
+        WHERE id = ? AND owner_email = ?`,
+      args: [
+        input.action,
+        input.summaryText ?? null,
+        input.createdBy ?? "user",
+        1,
+        input.originTurn ?? null,
+        now,
+        input.orgId ?? null,
+        row.id,
+        input.ownerEmail,
+      ],
+    });
+    return {
+      ...rowToDirective(row),
+      action: input.action,
+      summaryText: input.summaryText ?? null,
+      createdBy: input.createdBy ?? "user",
+      active: true,
+      originTurn: input.originTurn ?? null,
+      updatedAt: now,
+    };
+  }
+
+  const id = directiveId();
+  await client.execute({
+    sql: `INSERT INTO context_directives
+      (id, thread_id, segment_id, action, summary_text, created_by, active, origin_turn, created_at, updated_at, owner_email, org_id, visibility)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [
+      id,
+      input.threadId,
+      input.segmentId,
+      input.action,
+      input.summaryText ?? null,
+      input.createdBy ?? "user",
+      1,
+      input.originTurn ?? null,
+      now,
+      now,
+      input.ownerEmail,
+      input.orgId ?? null,
+      "private",
+    ],
+  });
+
+  return {
+    id,
+    threadId: input.threadId,
+    segmentId: input.segmentId,
+    action: input.action,
+    summaryText: input.summaryText ?? null,
+    createdBy: input.createdBy ?? "user",
+    active: true,
+    originTurn: input.originTurn ?? null,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export async function deactivateContextDirective(input: {
+  threadId: string;
+  segmentId: string;
+  ownerEmail: string;
+}): Promise<number> {
+  const result = await getDbExec().execute({
+    sql: `UPDATE context_directives SET active = ?, updated_at = ? WHERE thread_id = ? AND segment_id = ? AND owner_email = ?`,
+    args: [0, Date.now(), input.threadId, input.segmentId, input.ownerEmail],
+  });
+  return result.rowsAffected;
+}
+
+export async function readContextManifest(
+  threadId: string,
+): Promise<ContextManifest | null> {
+  return (await appStateGet(
+    threadId,
+    CONTEXT_XRAY_MANIFEST_KEY,
+  )) as unknown as ContextManifest | null;
+}
+
+export async function writeContextManifestStatus(input: {
+  threadId: string;
+  segmentId: string;
+  status: "active" | "pinned" | "evicted" | "summarized";
+}): Promise<ContextManifest | null> {
+  const current = await readContextManifest(input.threadId);
+  if (!current) return null;
+  const next = updateManifestSegmentStatus(
+    current,
+    input.segmentId,
+    input.status,
+  );
+  await appStatePut(
+    input.threadId,
+    CONTEXT_XRAY_MANIFEST_KEY,
+    next as unknown as Record<string, unknown>,
+    {
+      requestSource: "context-xray",
+    },
+  );
+  return next;
+}

package/src/agent/context-xray/identity.ts

@@ -0,0 +1,37 @@
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const obj = value as Record<string, unknown>;
+  return `{${Object.keys(obj)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`)
+    .join(",")}}`;
+}
+
+export function normalizeToolCallInputForIdentity(
+  input: unknown,
+): Record<string, unknown> {
+  if (input && typeof input === "object" && !Array.isArray(input)) {
+    return input as Record<string, unknown>;
+  }
+  return { rawInput: input };
+}
+
+export function parseToolInputForIdentity(input: unknown): unknown {
+  if (typeof input !== "string") return input;
+  try {
+    return JSON.parse(input);
+  } catch {
+    return input;
+  }
+}
+
+export function toolPairKey(toolName: string, input: unknown): string {
+  return `${toolName}:${stableStringify(
+    normalizeToolCallInputForIdentity(parseToolInputForIdentity(input)),
+  )}`;
+}