@agent-native/core 0.101.5 → 0.101.7

package/corpus/templates/content/server/db/schema.ts

@@ -12,6 +12,9 @@ export const documents = table("documents", {
   parentId: text("parent_id"),
   title: text("title").notNull().default("Untitled"),
   content: text("content").notNull().default(""),
+  // Stable semantic guidance for this page. Ancestry is computed at read time;
+  // never copy a parent's description here.
+  description: text("description").notNull().default(""),
   icon: text("icon"),
   position: integer("position").notNull().default(0),
   isFavorite: integer("is_favorite").notNull().default(0),
@@ -114,6 +117,7 @@ export const documentPropertyDefinitions = table(
     databaseId: text("database_id"),
     name: text("name").notNull(),
     type: text("type").notNull(),
+    description: text("description").notNull().default(""),
     visibility: text("visibility").notNull().default("always_show"),
     optionsJson: text("options_json").notNull().default("{}"),
     position: integer("position").notNull().default(0),

package/corpus/templates/content/server/lib/document-context.ts

@@ -0,0 +1,76 @@
+import { resolveAccess } from "@agent-native/core/sharing";
+import { and, eq, isNull } from "drizzle-orm";
+
+import { getDb, schema } from "../db/index.js";
+
+export type DocumentContextPathEntry = {
+  id: string;
+  kind: "page" | "database";
+  title: string;
+  description: string;
+};
+
+/** Focused-read context only: owned descriptions stay on their objects; this
+ * assembles the live path without copying ancestor prose into descendants. */
+export async function getDocumentContextPath(
+  document: Pick<typeof schema.documents.$inferSelect, "id" | "parentId">,
+): Promise<DocumentContextPathEntry[]> {
+  const db = getDb();
+  const path: DocumentContextPathEntry[] = [];
+  const seen = new Set<string>([document.id]);
+  let parentId = document.parentId;
+  while (parentId && !seen.has(parentId)) {
+    seen.add(parentId);
+    const parentAccess = await resolveAccess("document", parentId);
+    // A child share must not disclose prose from an inaccessible ancestor.
+    if (!parentAccess) break;
+    const parent = parentAccess.resource;
+    const [database] = await db
+      .select()
+      .from(schema.contentDatabases)
+      .where(
+        and(
+          eq(schema.contentDatabases.documentId, parent.id),
+          isNull(schema.contentDatabases.deletedAt),
+        ),
+      );
+    path.unshift({
+      id: database?.id ?? parent.id,
+      kind: database ? "database" : "page",
+      title: database?.title ?? parent.title,
+      description: parent.description,
+    });
+    parentId = parent.parentId;
+  }
+
+  const [membership] = await db
+    .select({ database: schema.contentDatabases })
+    .from(schema.contentDatabaseItems)
+    .innerJoin(
+      schema.contentDatabases,
+      eq(schema.contentDatabases.id, schema.contentDatabaseItems.databaseId),
+    )
+    .where(
+      and(
+        eq(schema.contentDatabaseItems.documentId, document.id),
+        isNull(schema.contentDatabases.deletedAt),
+      ),
+    );
+  if (
+    membership &&
+    !path.some((entry) => entry.id === membership.database.id)
+  ) {
+    const databaseDocumentAccess = await resolveAccess(
+      "document",
+      membership.database.documentId,
+    );
+    if (!databaseDocumentAccess) return path;
+    path.push({
+      id: membership.database.id,
+      kind: "database",
+      title: membership.database.title,
+      description: databaseDocumentAccess.resource.description,
+    });
+  }
+  return path;
+}

package/corpus/templates/content/server/lib/public-documents.ts

@@ -9,6 +9,7 @@ export const PUBLIC_DOCUMENT_CONTEXT_EXCERPT_CHARS = 2_400;
 type PublicDocumentPromptInput = {
   id: string;
   title: string;
+  description?: string;
   content: string;
   updatedAt: string | Date;
 };
@@ -44,6 +45,7 @@ ${fullDocumentGuidance}
 
 Document ID: ${doc.id}
 Title: ${doc.title}
+Description: ${doc.description || "(none)"}
 Updated at: ${doc.updatedAt}
 
 Markdown excerpt:
@@ -92,6 +94,7 @@ async function getPublicDocumentForEvent(event: H3Event) {
     .select({
       id: documents.id,
       title: documents.title,
+      description: documents.description,
       content: documents.content,
       updatedAt: documents.updatedAt,
       visibility: documents.visibility,

package/corpus/templates/content/server/plugins/db.ts

@@ -635,6 +635,12 @@ const runContentMigrations = runMigrations(
       sql: `CREATE INDEX IF NOT EXISTS document_property_values_document_property_idx ON document_property_values (document_id, property_id);
         CREATE INDEX IF NOT EXISTS document_property_values_property_document_idx ON document_property_values (property_id, document_id)`,
     },
+    {
+      version: 65,
+      name: "content-owned-descriptions",
+      sql: `ALTER TABLE documents ADD COLUMN IF NOT EXISTS description TEXT NOT NULL DEFAULT '';
+        ALTER TABLE document_property_definitions ADD COLUMN IF NOT EXISTS description TEXT NOT NULL DEFAULT ''`,
+    },
   ],
   { table: "content_migrations" },
 );

package/corpus/templates/content/server/routes/api/document-agent-context.json.get.ts

@@ -16,6 +16,7 @@ import {
   DOCUMENT_AGENT_RESOURCE_KIND,
 } from "../../../shared/agent-readable.js";
 import { getDb, schema } from "../../db/index.js";
+import { getDocumentContextPath } from "../../lib/document-context.js";
 
 function queryString(value: unknown): string {
   if (typeof value === "string") return value;
@@ -45,7 +46,9 @@ export default defineEventHandler(async (event) => {
   const [document] = await db
     .select({
       id: schema.documents.id,
+      parentId: schema.documents.parentId,
       title: schema.documents.title,
+      description: schema.documents.description,
       content: schema.documents.content,
       icon: schema.documents.icon,
       visibility: schema.documents.visibility,
@@ -77,11 +80,13 @@ export default defineEventHandler(async (event) => {
     resourceType: "document",
     id: document.id,
     title: document.title,
+    description: document.description,
     icon: document.icon,
     content: document.content,
     visibility: document.visibility,
     createdAt: document.createdAt,
     updatedAt: document.updatedAt,
+    contextPath: await getDocumentContextPath(document),
     url: buildContentPublicDocumentUrl(document.id, {
       basePath: getConfiguredAppBasePath(),
       token: tokenAccess ? token : null,

package/corpus/templates/content/shared/api.ts

@@ -8,11 +8,19 @@ import type {
 
 export type DocumentAccessRole = "owner" | "viewer" | "editor" | "admin";
 
+export interface ContentContextPathEntry {
+  id: string;
+  kind: "page" | "database";
+  title: string;
+  description: string;
+}
+
 export interface Document {
   id: string;
   parentId: string | null;
   title: string;
   content: string;
+  description?: string;
   icon: string | null;
   position: number;
   isFavorite: boolean;
@@ -27,6 +35,7 @@ export interface Document {
   properties?: DocumentProperty[];
   database?: ContentDatabase;
   databaseMembership?: ContentDatabaseMembership;
+  contextPath?: ContentContextPathEntry[];
   createdAt: string;
   updatedAt: string;
 }
@@ -90,12 +99,14 @@ export interface DocumentCreateRequest {
   title?: string;
   parentId?: string | null;
   content?: string;
+  description?: string;
   icon?: string;
 }
 
 export interface DocumentUpdateRequest {
   title?: string;
   content?: string;
+  description?: string;
   icon?: string | null;
   isFavorite?: boolean;
   loadedUpdatedAt?: string;
@@ -158,6 +169,7 @@ export interface DocumentPropertyDefinition {
   databaseId: string | null;
   name: string;
   type: DocumentPropertyType;
+  description?: string;
   visibility: DocumentPropertyVisibility;
   options: DocumentPropertyOptions;
   position: number;
@@ -182,6 +194,7 @@ export interface ConfigureDocumentPropertyRequest {
   documentId: string;
   name: string;
   type: DocumentPropertyType;
+  description?: string;
   visibility?: DocumentPropertyVisibility;
   options?: DocumentPropertyOptions;
 }
@@ -213,6 +226,7 @@ export interface ContentDatabase {
   id: string;
   documentId: string;
   title: string;
+  description?: string;
   viewConfig: ContentDatabaseViewConfig;
   createdAt: string;
   updatedAt: string;
@@ -692,6 +706,7 @@ export interface ContentDatabaseResponse {
   properties: DocumentProperty[];
   items: ContentDatabaseItem[];
   source: ContentDatabaseSource | null;
+  contextPath?: ContentContextPathEntry[];
   // All attached sources (NEXT). `source` stays as `sources[0] ?? null` for
   // back-compat; multi-source consumers read `sources`.
   sources?: ContentDatabaseSource[];
@@ -737,11 +752,13 @@ export interface CreateDatabaseRequest {
   documentId?: string;
   parentId?: string | null;
   title?: string;
+  description?: string;
 }
 
 export interface CreateInlineDatabaseRequest {
   hostDocumentId: string;
   title?: string;
+  description?: string;
 }
 
 export interface CreateInlineDatabaseResponse {

package/corpus/templates/content/shared/content-source.ts

@@ -6,6 +6,7 @@ export interface ContentSourceDocument {
   parentId: string | null;
   title: string;
   content: string;
+  description?: string;
   icon: string | null;
   position: number;
   isFavorite: boolean;
@@ -31,6 +32,7 @@ export interface ParsedContentSourceFile {
   parentId?: string | null;
   title: string;
   content: string;
+  description?: string;
   icon?: string | null;
   position?: number;
   isFavorite?: boolean;
@@ -152,6 +154,7 @@ export function serializeContentSourceDocument(
   const frontmatter = [
     frontmatterLine("id", doc.id),
     frontmatterLine("title", doc.title || "Untitled"),
+    frontmatterLine("description", doc.description),
     frontmatterLine("parentId", doc.parentId),
     frontmatterLine("icon", doc.icon),
     frontmatterLine("position", doc.position),
@@ -196,6 +199,10 @@ export function parseContentSourceFile(
     parentId,
     title,
     content,
+    description:
+      typeof metadata.description === "string"
+        ? metadata.description
+        : undefined,
     icon: hasOwn(metadata, "icon")
       ? typeof metadata.icon === "string"
         ? metadata.icon

package/corpus/templates/content/shared/properties.ts

@@ -89,6 +89,8 @@ export interface DocumentPropertyOption {
   id: string;
   name: string;
   color: DocumentPropertyOptionColor;
+  /** Stable guidance for when this select/status value should be chosen. */
+  description?: string;
 }
 
 export interface DocumentPropertyOptions {

package/dist/a2a/artifact-response.d.ts

@@ -5,7 +5,22 @@ export interface A2AToolResultSummary {
 export interface A2AArtifactResponseOptions {
     baseUrl?: string;
     includeReferencedArtifacts?: boolean;
+    includePersistedArtifactMarker?: boolean;
 }
+export interface A2AArtifactIdentity {
+    resourceType: "document" | "deck" | "dashboard" | "analysis" | "image" | "design" | "monitor" | "form";
+    id: string;
+    sourceAction: string;
+    titleAtAction?: string;
+    url?: string;
+}
+export declare function stripA2APersistedArtifactMarkers(text: string): string;
+/**
+ * Extract a compact, verified identity ledger from successful artifact tools.
+ * The ledger deliberately excludes raw tool results so it is safe to retain in
+ * long-lived thread context and stable even when a resource is later renamed.
+ */
+export declare function extractA2AArtifactIdentities(results: A2AToolResultSummary[]): A2AArtifactIdentity[];
 export declare function appendA2AArtifactLinks(responseText: string, toolResults: A2AToolResultSummary[], options?: A2AArtifactResponseOptions): string;
 export declare function buildA2ARecoverableArtifactMessage(toolResults: A2AToolResultSummary[], options?: A2AArtifactResponseOptions): string | null;
 //# sourceMappingURL=artifact-response.d.ts.map

package/dist/a2a/artifact-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-response.d.ts","sourceRoot":"","sources":["../../src/a2a/artifact-response.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AA6lCD,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,CAsIR;AAED,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,GAAG,IAAI,CA8Bf"}
+{"version":3,"file":"artifact-response.d.ts","sourceRoot":"","sources":["../../src/a2a/artifact-response.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,8BAA8B,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EACR,UAAU,GACV,MAAM,GACN,WAAW,GACX,UAAU,GACV,OAAO,GACP,QAAQ,GACR,SAAS,GACT,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAgGD,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AA8tBD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,oBAAoB,EAAE,GAC9B,mBAAmB,EAAE,CAmGvB;AA2YD,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,CA8IR;AAED,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,oBAAoB,EAAE,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,GAAG,IAAI,CA8Bf"}

package/dist/a2a/artifact-response.js

@@ -1,3 +1,88 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const ARTIFACT_IDENTITY_WRITE_TOOLS = new Set([
+    "save-monitor",
+    "create-form",
+    "submit-content-database-form",
+    "add-database-item",
+    "create-document",
+    "update-document",
+    "create-deck",
+    "duplicate-deck",
+    "add-slide",
+    "update-dashboard",
+    "rename-dashboard",
+    "save-analysis",
+    "generate-image",
+    "edit-image",
+    "refine-image",
+    "restyle-image",
+    "save-generated-image",
+    "save-generated-asset",
+    "export-image",
+    "export-asset",
+    "generate-image-batch",
+    "create-design",
+    "generate-design",
+    "create-file",
+    "duplicate-design",
+]);
+const PERSISTED_ARTIFACT_MARKER = "agent-native:persisted-artifacts=";
+const PERSISTED_ARTIFACT_MARKER_PATTERN = /\s*<!--\s*agent-native:persisted-artifacts=[A-Za-z0-9_-]+\.[a-f0-9]{64}\s*-->/g;
+const ARTIFACT_RESOURCE_TYPES = new Set([
+    "document",
+    "deck",
+    "dashboard",
+    "analysis",
+    "image",
+    "design",
+    "monitor",
+    "form",
+]);
+function persistedArtifactIdentitiesFromMarker(result) {
+    const secret = process.env.A2A_SECRET;
+    if (!secret)
+        return [];
+    const match = result.match(/<!--\s*agent-native:persisted-artifacts=([A-Za-z0-9_-]+)\.([a-f0-9]{64})\s*-->/);
+    if (!match)
+        return [];
+    try {
+        const payload = match[1];
+        const expected = createHmac("sha256", secret).update(payload).digest();
+        const supplied = Buffer.from(match[2], "hex");
+        if (supplied.length !== expected.length ||
+            !timingSafeEqual(supplied, expected)) {
+            return [];
+        }
+        const parsed = JSON.parse(Buffer.from(payload, "base64url").toString());
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .slice(0, 12)
+            .filter((identity) => {
+            const item = asRecord(identity);
+            return (!!item &&
+                ARTIFACT_RESOURCE_TYPES.has(item.resourceType) &&
+                typeof item.id === "string" &&
+                typeof item.sourceAction === "string");
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function withPersistedArtifactMarker(text, toolResults) {
+    const identities = extractA2AArtifactIdentities(toolResults).slice(0, 12);
+    const secret = process.env.A2A_SECRET;
+    if (identities.length === 0 || !secret)
+        return text;
+    const payload = Buffer.from(JSON.stringify(identities)).toString("base64url");
+    const signature = createHmac("sha256", secret).update(payload).digest("hex");
+    const marker = `<!-- ${PERSISTED_ARTIFACT_MARKER}${payload}.${signature} -->`;
+    return text ? `${text}\n\n${marker}` : marker;
+}
+export function stripA2APersistedArtifactMarkers(text) {
+    return text.replace(PERSISTED_ARTIFACT_MARKER_PATTERN, "").trim();
+}
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -450,13 +535,22 @@ function collectArtifacts(results) {
             continue;
         }
         if (toolResult.tool === "generate-image" ||
+            toolResult.tool === "edit-image" ||
             toolResult.tool === "refine-image" ||
+            toolResult.tool === "restyle-image" ||
             toolResult.tool === "get-asset" ||
             toolResult.tool === "save-generated-image" ||
+            toolResult.tool === "save-generated-asset" ||
             toolResult.tool === "export-image") {
             addImageArtifact(images, parsed);
             continue;
         }
+        if (toolResult.tool === "export-asset") {
+            if (stringValue(parsed.artifactType) === "image") {
+                addImageArtifact(images, parsed);
+            }
+            continue;
+        }
         if (toolResult.tool === "generate-image-batch") {
             if (Array.isArray(parsed.images)) {
                 for (const item of parsed.images) {
@@ -553,6 +647,107 @@ function collectArtifacts(results) {
         forms: [...forms.values()],
     };
 }
+/**
+ * Extract a compact, verified identity ledger from successful artifact tools.
+ * The ledger deliberately excludes raw tool results so it is safe to retain in
+ * long-lived thread context and stable even when a resource is later renamed.
+ */
+export function extractA2AArtifactIdentities(results) {
+    const identities = new Map();
+    const remember = (identity) => {
+        identities.set(`${identity.resourceType}:${identity.id}`, identity);
+    };
+    for (const result of results) {
+        if (result.tool === "call-agent") {
+            for (const identity of persistedArtifactIdentitiesFromMarker(result.result)) {
+                remember({ ...identity, sourceAction: "call-agent" });
+            }
+            continue;
+        }
+        if (!ARTIFACT_IDENTITY_WRITE_TOOLS.has(result.tool))
+            continue;
+        const artifacts = collectArtifacts([result]);
+        for (const document of artifacts.documents) {
+            remember({
+                resourceType: "document",
+                id: document.id,
+                sourceAction: result.tool,
+                titleAtAction: document.title,
+                url: document.url,
+            });
+        }
+        for (const deck of artifacts.decks) {
+            remember({
+                resourceType: "deck",
+                id: deck.id,
+                sourceAction: result.tool,
+                url: deck.url,
+            });
+        }
+        for (const dashboard of artifacts.dashboards) {
+            remember({
+                resourceType: "dashboard",
+                id: dashboard.id,
+                sourceAction: result.tool,
+                titleAtAction: dashboard.title,
+                url: dashboard.url,
+            });
+        }
+        for (const analysis of artifacts.analyses) {
+            remember({
+                resourceType: "analysis",
+                id: analysis.id,
+                sourceAction: result.tool,
+                titleAtAction: analysis.title,
+                url: analysis.url,
+            });
+        }
+        for (const image of artifacts.images) {
+            remember({
+                resourceType: "image",
+                id: image.id,
+                sourceAction: result.tool,
+                titleAtAction: image.title,
+                url: image.url,
+            });
+        }
+        for (const design of artifacts.designShells) {
+            remember({
+                resourceType: "design",
+                id: design.id,
+                sourceAction: result.tool,
+                titleAtAction: design.title,
+            });
+        }
+        for (const design of artifacts.generatedDesigns) {
+            remember({
+                resourceType: "design",
+                id: design.id,
+                sourceAction: result.tool,
+                url: design.url,
+            });
+        }
+        for (const monitor of artifacts.monitors) {
+            remember({
+                resourceType: "monitor",
+                id: monitor.id,
+                sourceAction: result.tool,
+                titleAtAction: monitor.name,
+                url: monitor.url,
+            });
+        }
+        for (const form of artifacts.forms) {
+            remember({
+                resourceType: "form",
+                id: form.id,
+                sourceAction: result.tool,
+                titleAtAction: form.title,
+                url: form.url,
+            });
+        }
+    }
+    return [...identities.values()];
+}
 function parseDownstreamArtifactBlock(result) {
     const artifacts = [];
     for (const line of downstreamArtifactLines(result)) {
@@ -857,6 +1052,9 @@ function formatUnverifiedArtifactMessage(refs, documents, decks, dashboards, ana
 export function appendA2AArtifactLinks(responseText, toolResults, options = {}) {
     const baseUrl = normalizeBaseUrl(options.baseUrl);
     const includeReferencedArtifacts = options.includeReferencedArtifacts ?? false;
+    const finalize = (value) => options.includePersistedArtifactMarker
+        ? withPersistedArtifactMarker(value, toolResults)
+        : value;
     const { documents, decks, dashboards, analyses, images, designShells, generatedDesigns, monitors, forms, } = collectArtifacts(toolResults);
     const generatedDesignIds = new Set(generatedDesigns.map((design) => design.id));
     const incompleteShells = designShells.filter((shell) => !generatedDesignIds.has(shell.id));
@@ -866,11 +1064,11 @@ export function appendA2AArtifactLinks(responseText, toolResults, options = {})
         !responseAlreadyWarnsIncompleteDesign(text) &&
         (incompleteShells.some((shell) => responseMentionsDesignShell(text, shell)) ||
             /\b(?:done|created|ready|here(?:'s| is)|complete|finished)\b/i.test(text))) {
-        return formatIncompleteDesignMessage(incompleteShells);
+        return finalize(formatIncompleteDesignMessage(incompleteShells));
     }
     const unverifiedRefs = findUnverifiedArtifactReferences(text, baseUrl, documents, decks, dashboards, analyses, images, generatedDesigns);
     if (unverifiedRefs.length > 0) {
-        return formatUnverifiedArtifactMessage(unverifiedRefs, documents, decks, dashboards, analyses, images, generatedDesigns, baseUrl);
+        return finalize(formatUnverifiedArtifactMessage(unverifiedRefs, documents, decks, dashboards, analyses, images, generatedDesigns, baseUrl));
     }
     const missingLines = [];
     for (const document of documents) {
@@ -927,10 +1125,11 @@ export function appendA2AArtifactLinks(responseText, toolResults, options = {})
             missingLines.push(formatFormLine(form));
         }
     }
-    if (missingLines.length === 0)
-        return text;
+    if (missingLines.length === 0) {
+        return finalize(text);
+    }
     const artifactBlock = `Artifacts:\n${missingLines.join("\n")}`;
-    return text ? `${text}\n\n${artifactBlock}` : artifactBlock;
+    return finalize(text ? `${text}\n\n${artifactBlock}` : artifactBlock);
 }
 export function buildA2ARecoverableArtifactMessage(toolResults, options = {}) {
     const baseUrl = normalizeBaseUrl(options.baseUrl);