@agent-native/core 0.46.0 → 0.48.1

package/dist/shared/streaming-text-smoothing.d.ts

@@ -1,7 +1,25 @@
 export declare const SMOOTH_STREAMING_COMMIT_INTERVAL_MS = 16;
 export declare const SMOOTH_STREAMING_LONG_TEXT_THRESHOLD_GRAPHEMES = 640;
 export declare const SMOOTH_STREAMING_LONG_TEXT_TAIL_GRAPHEMES = 180;
+/**
+ * Split `text` into grapheme clusters.
+ *
+ * Results are cached: when `text` is an append of a previously segmented
+ * string, only the appended suffix is segmented (plus a small overlap) and
+ * merged with the cached result, making this O(delta) instead of O(n) per
+ * call.
+ *
+ * When the new text is not a prefix-extension of the cache (e.g. a full reset
+ * or non-append change) we fall back to full segmentation and reset the cache.
+ */
 export declare function splitStreamingTextGraphemes(text: string): string[];
+/**
+ * Reset the incremental segmentation cache.  Call this when switching to a
+ * new message so the cache from the previous message isn't carried over.
+ * (Not strictly necessary for correctness — the cache is keyed on content —
+ * but avoids holding a reference to the last message's text string.)
+ */
+export declare function resetSegmenterCache(): void;
 export declare function initialSmoothStreamingGraphemeCount(graphemes: readonly string[]): number;
 export declare function smoothStreamingRevealCount({ backlog, elapsedMs, inputDone, }: {
     backlog: number;

package/dist/shared/streaming-text-smoothing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming-text-smoothing.d.ts","sourceRoot":"","sources":["../../src/shared/streaming-text-smoothing.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mCAAmC,KAAK,CAAC;AACtD,eAAO,MAAM,8CAA8C,MAAM,CAAC;AAClE,eAAO,MAAM,yCAAyC,MAAM,CAAC;AAW7D,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAWlE;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,CASR;AAED,wBAAgB,0BAA0B,CAAC,EACzC,OAAO,EACP,SAAS,EACT,SAAiB,GAClB,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,MAAM,CAqBT;AAED,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,MAAM,GACd,MAAM,CAkBR"}
+{"version":3,"file":"streaming-text-smoothing.d.ts","sourceRoot":"","sources":["../../src/shared/streaming-text-smoothing.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mCAAmC,KAAK,CAAC;AACtD,eAAO,MAAM,8CAA8C,MAAM,CAAC;AAClE,eAAO,MAAM,yCAAyC,MAAM,CAAC;AA2C7D;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CA6ClE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,CASR;AAED,wBAAgB,0BAA0B,CAAC,EACzC,OAAO,EACP,SAAS,EACT,SAAiB,GAClB,EAAE;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,MAAM,CAqBT;AAED,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,MAAM,GACd,MAAM,CAkBR"}

package/dist/shared/streaming-text-smoothing.js

@@ -1,13 +1,79 @@
 export const SMOOTH_STREAMING_COMMIT_INTERVAL_MS = 16;
 export const SMOOTH_STREAMING_LONG_TEXT_THRESHOLD_GRAPHEMES = 640;
 export const SMOOTH_STREAMING_LONG_TEXT_TAIL_GRAPHEMES = 180;
-export function splitStreamingTextGraphemes(text) {
+// Module-level singleton Segmenter instance — creating a new Segmenter on every
+// call was previously the hot path cost (allocation + engine init per chunk).
+let _segmenter = undefined; // undefined = not yet checked
+function getSegmenter() {
+    if (_segmenter !== undefined)
+        return _segmenter;
     const Segmenter = Intl
         .Segmenter;
-    if (Segmenter) {
-        return Array.from(new Segmenter(undefined, { granularity: "grapheme" }).segment(text), (entry) => entry.segment);
+    _segmenter = Segmenter
+        ? new Segmenter(undefined, { granularity: "grapheme" })
+        : null;
+    return _segmenter;
+}
+/**
+ * Incremental segmentation cache.  Instead of re-segmenting the full target
+ * text on every frame, we extend the cached grapheme array by only segmenting
+ * newly appended text.
+ *
+ * Because multi-byte grapheme clusters (emoji, ZWJ sequences) can straddle a
+ * chunk boundary we re-segment the last OVERLAP characters of the previous text
+ * together with the new suffix, then splice the results in.
+ */
+const SEGMENTER_OVERLAP = 16; // chars — safely covers any real grapheme cluster
+let _segCache = null;
+/**
+ * Split `text` into grapheme clusters.
+ *
+ * Results are cached: when `text` is an append of a previously segmented
+ * string, only the appended suffix is segmented (plus a small overlap) and
+ * merged with the cached result, making this O(delta) instead of O(n) per
+ * call.
+ *
+ * When the new text is not a prefix-extension of the cache (e.g. a full reset
+ * or non-append change) we fall back to full segmentation and reset the cache.
+ */
+export function splitStreamingTextGraphemes(text) {
+    const segmenter = getSegmenter();
+    if (!segmenter) {
+        return Array.from(text);
     }
-    return Array.from(text);
+    // Fast path: exact cache hit
+    if (_segCache && _segCache.text === text) {
+        return _segCache.graphemes;
+    }
+    // Incremental path: new text extends the cached text
+    if (_segCache && text.startsWith(_segCache.text)) {
+        const prevLen = _segCache.text.length;
+        // Re-segment from (prevLen - OVERLAP) to include the overlap so any
+        // grapheme that was split across the boundary is correctly re-assembled.
+        const overlapStart = Math.max(0, prevLen - SEGMENTER_OVERLAP);
+        const suffix = text.slice(overlapStart);
+        const newGraphemes = Array.from(segmenter.segment(suffix), (entry) => entry.segment);
+        // Drop graphemes that correspond to the overlap region from the cache so
+        // we don't double-count them.
+        const overlapGraphemes = Array.from(segmenter.segment(text.slice(overlapStart, prevLen)), (entry) => entry.segment);
+        const stableGraphemes = _segCache.graphemes.slice(0, _segCache.graphemes.length - overlapGraphemes.length);
+        const merged = stableGraphemes.concat(newGraphemes);
+        _segCache = { text, graphemes: merged };
+        return merged;
+    }
+    // Full fallback: text is not an append of cached text (reset or replacement)
+    const graphemes = Array.from(segmenter.segment(text), (entry) => entry.segment);
+    _segCache = { text, graphemes };
+    return graphemes;
+}
+/**
+ * Reset the incremental segmentation cache.  Call this when switching to a
+ * new message so the cache from the previous message isn't carried over.
+ * (Not strictly necessary for correctness — the cache is keyed on content —
+ * but avoids holding a reference to the last message's text string.)
+ */
+export function resetSegmenterCache() {
+    _segCache = null;
 }
 export function initialSmoothStreamingGraphemeCount(graphemes) {
     if (graphemes.length <= SMOOTH_STREAMING_LONG_TEXT_THRESHOLD_GRAPHEMES) {

package/dist/shared/streaming-text-smoothing.js.map

@@ -1 +1 @@
-{"version":3,"file":"streaming-text-smoothing.js","sourceRoot":"","sources":["../../src/shared/streaming-text-smoothing.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mCAAmC,GAAG,EAAE,CAAC;AACtD,MAAM,CAAC,MAAM,8CAA8C,GAAG,GAAG,CAAC;AAClE,MAAM,CAAC,MAAM,yCAAyC,GAAG,GAAG,CAAC;AAW7D,MAAM,UAAU,2BAA2B,CAAC,IAAY;IACtD,MAAM,SAAS,GAAI,IAA2D;SAC3E,SAAS,CAAC;IACb,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,KAAK,CAAC,IAAI,CACf,IAAI,SAAS,CAAC,SAAS,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EACnE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CACzB,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,mCAAmC,CACjD,SAA4B;IAE5B,IAAI,SAAS,CAAC,MAAM,IAAI,8CAA8C,EAAE,CAAC;QACvE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CACb,CAAC,EACD,SAAS,CAAC,MAAM,GAAG,yCAAyC,CAC7D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,EACzC,OAAO,EACP,SAAS,EACT,SAAS,GAAG,KAAK,GAKlB;IACC,IAAI,OAAO,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,mBAAmB,GAAG,SAAS;QACnC,CAAC,CAAC,OAAO,GAAG,GAAG;YACb,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,GAAG;QACP,CAAC,CAAC,OAAO,GAAG,IAAI;YACd,CAAC,CAAC,GAAG;YACL,CAAC,CAAC,OAAO,GAAG,GAAG;gBACb,CAAC,CAAC,GAAG;gBACL,CAAC,CAAC,OAAO,GAAG,GAAG;oBACb,CAAC,CAAC,GAAG;oBACL,CAAC,CAAC,EAAE,CAAC;IAEb,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,mBAAmB,CAAC,CAAC;IAEnE,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,iCAAiC,CAC/C,QAA4B,EAC5B,OAAe;IAEf,IAAI,CAAC,QAAQ,IAAI,OAAO,GAAG,GAAG,EAAE,CAAC;QAC/B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC","sourcesContent":["export const SMOOTH_STREAMING_COMMIT_INTERVAL_MS = 16;\nexport const SMOOTH_STREAMING_LONG_TEXT_THRESHOLD_GRAPHEMES = 640;\nexport const SMOOTH_STREAMING_LONG_TEXT_TAIL_GRAPHEMES = 180;\n\ntype SegmenterInstance = {\n  segment(input: string): Iterable<{ segment: string }>;\n};\n\ntype SegmenterConstructor = new (\n  locales?: string | string[],\n  options?: { granularity?: \"grapheme\" },\n) => SegmenterInstance;\n\nexport function splitStreamingTextGraphemes(text: string): string[] {\n  const Segmenter = (Intl as typeof Intl & { Segmenter?: SegmenterConstructor })\n    .Segmenter;\n  if (Segmenter) {\n    return Array.from(\n      new Segmenter(undefined, { granularity: \"grapheme\" }).segment(text),\n      (entry) => entry.segment,\n    );\n  }\n\n  return Array.from(text);\n}\n\nexport function initialSmoothStreamingGraphemeCount(\n  graphemes: readonly string[],\n): number {\n  if (graphemes.length <= SMOOTH_STREAMING_LONG_TEXT_THRESHOLD_GRAPHEMES) {\n    return 0;\n  }\n\n  return Math.max(\n    0,\n    graphemes.length - SMOOTH_STREAMING_LONG_TEXT_TAIL_GRAPHEMES,\n  );\n}\n\nexport function smoothStreamingRevealCount({\n  backlog,\n  elapsedMs,\n  inputDone = false,\n}: {\n  backlog: number;\n  elapsedMs: number;\n  inputDone?: boolean;\n}): number {\n  if (backlog <= 0 || elapsedMs <= 0) {\n    return 0;\n  }\n\n  const charactersPerSecond = inputDone\n    ? backlog > 800\n      ? 900\n      : 420\n    : backlog > 1400\n      ? 640\n      : backlog > 520\n        ? 360\n        : backlog > 180\n          ? 190\n          : 95;\n\n  const maxBurst = inputDone ? 160 : backlog > 1400 ? 120 : 72;\n  const count = Math.floor((elapsedMs / 1000) * charactersPerSecond);\n\n  return Math.min(backlog, Math.max(1, count), maxBurst);\n}\n\nexport function smoothStreamingPunctuationDelayMs(\n  grapheme: string | undefined,\n  backlog: number,\n): number {\n  if (!grapheme || backlog > 220) {\n    return 0;\n  }\n\n  if (grapheme === \"\\n\") {\n    return 80;\n  }\n\n  if (/[.!?)]/.test(grapheme)) {\n    return 70;\n  }\n\n  if (/[,;:]/.test(grapheme)) {\n    return 35;\n  }\n\n  return 0;\n}\n"]}
+{"version":3,"file":"streaming-text-smoothing.js","sourceRoot":"","sources":["../../src/shared/streaming-text-smoothing.ts"],"names":[],"mappings":"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","sourcesContent":["export const SMOOTH_STREAMING_COMMIT_INTERVAL_MS = 16;\nexport const SMOOTH_STREAMING_LONG_TEXT_THRESHOLD_GRAPHEMES = 640;\nexport const SMOOTH_STREAMING_LONG_TEXT_TAIL_GRAPHEMES = 180;\n\ntype SegmenterInstance = {\n  segment(input: string): Iterable<{ segment: string }>;\n};\n\ntype SegmenterConstructor = new (\n  locales?: string | string[],\n  options?: { granularity?: \"grapheme\" },\n) => SegmenterInstance;\n\n// Module-level singleton Segmenter instance — creating a new Segmenter on every\n// call was previously the hot path cost (allocation + engine init per chunk).\nlet _segmenter: SegmenterInstance | null | undefined = undefined; // undefined = not yet checked\n\nfunction getSegmenter(): SegmenterInstance | null {\n  if (_segmenter !== undefined) return _segmenter;\n  const Segmenter = (Intl as typeof Intl & { Segmenter?: SegmenterConstructor })\n    .Segmenter;\n  _segmenter = Segmenter\n    ? new Segmenter(undefined, { granularity: \"grapheme\" })\n    : null;\n  return _segmenter;\n}\n\n/**\n * Incremental segmentation cache.  Instead of re-segmenting the full target\n * text on every frame, we extend the cached grapheme array by only segmenting\n * newly appended text.\n *\n * Because multi-byte grapheme clusters (emoji, ZWJ sequences) can straddle a\n * chunk boundary we re-segment the last OVERLAP characters of the previous text\n * together with the new suffix, then splice the results in.\n */\nconst SEGMENTER_OVERLAP = 16; // chars — safely covers any real grapheme cluster\n\ninterface SegmenterCache {\n  text: string;\n  graphemes: string[];\n}\n\nlet _segCache: SegmenterCache | null = null;\n\n/**\n * Split `text` into grapheme clusters.\n *\n * Results are cached: when `text` is an append of a previously segmented\n * string, only the appended suffix is segmented (plus a small overlap) and\n * merged with the cached result, making this O(delta) instead of O(n) per\n * call.\n *\n * When the new text is not a prefix-extension of the cache (e.g. a full reset\n * or non-append change) we fall back to full segmentation and reset the cache.\n */\nexport function splitStreamingTextGraphemes(text: string): string[] {\n  const segmenter = getSegmenter();\n\n  if (!segmenter) {\n    return Array.from(text);\n  }\n\n  // Fast path: exact cache hit\n  if (_segCache && _segCache.text === text) {\n    return _segCache.graphemes;\n  }\n\n  // Incremental path: new text extends the cached text\n  if (_segCache && text.startsWith(_segCache.text)) {\n    const prevLen = _segCache.text.length;\n    // Re-segment from (prevLen - OVERLAP) to include the overlap so any\n    // grapheme that was split across the boundary is correctly re-assembled.\n    const overlapStart = Math.max(0, prevLen - SEGMENTER_OVERLAP);\n    const suffix = text.slice(overlapStart);\n    const newGraphemes = Array.from(\n      segmenter.segment(suffix),\n      (entry) => entry.segment,\n    );\n    // Drop graphemes that correspond to the overlap region from the cache so\n    // we don't double-count them.\n    const overlapGraphemes = Array.from(\n      segmenter.segment(text.slice(overlapStart, prevLen)),\n      (entry) => entry.segment,\n    );\n    const stableGraphemes = _segCache.graphemes.slice(\n      0,\n      _segCache.graphemes.length - overlapGraphemes.length,\n    );\n    const merged = stableGraphemes.concat(newGraphemes);\n    _segCache = { text, graphemes: merged };\n    return merged;\n  }\n\n  // Full fallback: text is not an append of cached text (reset or replacement)\n  const graphemes = Array.from(\n    segmenter.segment(text),\n    (entry) => entry.segment,\n  );\n  _segCache = { text, graphemes };\n  return graphemes;\n}\n\n/**\n * Reset the incremental segmentation cache.  Call this when switching to a\n * new message so the cache from the previous message isn't carried over.\n * (Not strictly necessary for correctness — the cache is keyed on content —\n * but avoids holding a reference to the last message's text string.)\n */\nexport function resetSegmenterCache(): void {\n  _segCache = null;\n}\n\nexport function initialSmoothStreamingGraphemeCount(\n  graphemes: readonly string[],\n): number {\n  if (graphemes.length <= SMOOTH_STREAMING_LONG_TEXT_THRESHOLD_GRAPHEMES) {\n    return 0;\n  }\n\n  return Math.max(\n    0,\n    graphemes.length - SMOOTH_STREAMING_LONG_TEXT_TAIL_GRAPHEMES,\n  );\n}\n\nexport function smoothStreamingRevealCount({\n  backlog,\n  elapsedMs,\n  inputDone = false,\n}: {\n  backlog: number;\n  elapsedMs: number;\n  inputDone?: boolean;\n}): number {\n  if (backlog <= 0 || elapsedMs <= 0) {\n    return 0;\n  }\n\n  const charactersPerSecond = inputDone\n    ? backlog > 800\n      ? 900\n      : 420\n    : backlog > 1400\n      ? 640\n      : backlog > 520\n        ? 360\n        : backlog > 180\n          ? 190\n          : 95;\n\n  const maxBurst = inputDone ? 160 : backlog > 1400 ? 120 : 72;\n  const count = Math.floor((elapsedMs / 1000) * charactersPerSecond);\n\n  return Math.min(backlog, Math.max(1, count), maxBurst);\n}\n\nexport function smoothStreamingPunctuationDelayMs(\n  grapheme: string | undefined,\n  backlog: number,\n): number {\n  if (!grapheme || backlog > 220) {\n    return 0;\n  }\n\n  if (grapheme === \"\\n\") {\n    return 80;\n  }\n\n  if (/[.!?)]/.test(grapheme)) {\n    return 70;\n  }\n\n  if (/[,;:]/.test(grapheme)) {\n    return 35;\n  }\n\n  return 0;\n}\n"]}

package/dist/sharing/actions/list-resource-shares.d.ts

@@ -1,3 +1,26 @@
-declare const _default: any;
+declare const _default: import("../../action.js").ActionDefinition<{
+    resourceType: string;
+    resourceId: string;
+}, {
+    ownerEmail: null;
+    visibility: null;
+    shares: never[];
+    policy: {
+        allowPublic: boolean;
+        requireOrgMemberForUserShares: boolean;
+    };
+    orgId?: undefined;
+    role?: undefined;
+} | {
+    ownerEmail: any;
+    orgId: any;
+    visibility: any;
+    role: "owner" | import("../schema.js").ShareRole;
+    shares: any;
+    policy: {
+        allowPublic: boolean;
+        requireOrgMemberForUserShares: boolean;
+    };
+}>;
 export default _default;
 //# sourceMappingURL=list-resource-shares.d.ts.map

package/dist/sharing/actions/list-resource-shares.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-resource-shares.d.ts","sourceRoot":"","sources":["../../../src/sharing/actions/list-resource-shares.ts"],"names":[],"mappings":";AAMA,wBAyCG"}
+{"version":3,"file":"list-resource-shares.d.ts","sourceRoot":"","sources":["../../../src/sharing/actions/list-resource-shares.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAMA,wBAyCG"}

package/dist/sharing/actions/set-resource-visibility.d.ts

@@ -1,3 +1,10 @@
-declare const _default: any;
+declare const _default: import("../../action.js").ActionDefinition<{
+    resourceType: string;
+    resourceId: string;
+    visibility: "org" | "private" | "public";
+}, {
+    ok: boolean;
+    visibility: "org" | "private" | "public";
+}>;
 export default _default;
 //# sourceMappingURL=set-resource-visibility.d.ts.map

package/dist/sharing/actions/set-resource-visibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set-resource-visibility.d.ts","sourceRoot":"","sources":["../../../src/sharing/actions/set-resource-visibility.ts"],"names":[],"mappings":";AAeA,wBA2DG"}
+{"version":3,"file":"set-resource-visibility.d.ts","sourceRoot":"","sources":["../../../src/sharing/actions/set-resource-visibility.ts"],"names":[],"mappings":";;;;;;;;AAeA,wBA2DG"}

package/dist/sharing/actions/share-resource.d.ts

@@ -1,5 +1,16 @@
 export declare function isSyntheticQaEmail(email: string): boolean;
 export declare function resolveShareNotificationUrl(explicitUrl: string | undefined, fallbackPath: string | undefined, appUrl?: string): string;
-declare const _default: any;
+declare const _default: import("../../action.js").ActionDefinition<{
+    resourceType: string;
+    resourceId: string;
+    principalType: "user" | "org";
+    principalId: string;
+    role?: "editor" | "admin" | "viewer" | undefined;
+    notify?: boolean | undefined;
+    resourceUrl?: string | undefined;
+}, {
+    id: any;
+    updated: boolean;
+}>;
 export default _default;
 //# sourceMappingURL=share-resource.d.ts.map

package/dist/sharing/actions/share-resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"share-resource.d.ts","sourceRoot":"","sources":["../../../src/sharing/actions/share-resource.ts"],"names":[],"mappings":"AAeA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAazD;AAwCD,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,MAAM,SAAwB,GAC7B,MAAM,CAOR;;AAwCD,wBAsKG"}
+{"version":3,"file":"share-resource.d.ts","sourceRoot":"","sources":["../../../src/sharing/actions/share-resource.ts"],"names":[],"mappings":"AAeA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAazD;AAwCD,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,MAAM,SAAwB,GAC7B,MAAM,CAOR;;;;;;;;;;;;;AAwCD,wBAsKG"}

package/dist/sharing/actions/unshare-resource.d.ts

@@ -1,3 +1,10 @@
-declare const _default: any;
+declare const _default: import("../../action.js").ActionDefinition<{
+    resourceType: string;
+    resourceId: string;
+    principalType: "user" | "org";
+    principalId: string;
+}, {
+    ok: boolean;
+}>;
 export default _default;
 //# sourceMappingURL=unshare-resource.d.ts.map

package/dist/sharing/actions/unshare-resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unshare-resource.d.ts","sourceRoot":"","sources":["../../../src/sharing/actions/unshare-resource.ts"],"names":[],"mappings":";AAUA,wBAmCG"}
+{"version":3,"file":"unshare-resource.d.ts","sourceRoot":"","sources":["../../../src/sharing/actions/unshare-resource.ts"],"names":[],"mappings":";;;;;;;;AAUA,wBAmCG"}

package/dist/sharing/schema.d.ts

@@ -31,9 +31,9 @@
  * - `visibility`— coarse default: `'private' | 'org' | 'public'`. Default `'private'`.
  */
 export declare function ownableColumns(): {
-    ownerEmail: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"owner_email", [string, ...string[]], number>>>;
-    orgId: import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"org_id", [string, ...string[]], number>;
-    visibility: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"visibility", ["private", "org", "public"], number>>>;
+    ownerEmail: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"owner_email", [string, ...string[]], number | undefined>>>;
+    orgId: import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"org_id", [string, ...string[]], number | undefined>;
+    visibility: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/sqlite-core").SQLiteTextBuilderInitial<"visibility", ["private", "org", "public"], number | undefined>>>;
 };
 /**
  * Create a companion shares table for an ownable resource. Call this right
@@ -74,7 +74,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number;
+            length: number | undefined;
         }>;
         resourceId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "resource_id";
@@ -93,7 +93,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number;
+            length: number | undefined;
         }>;
         principalType: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "principal_type";
@@ -112,7 +112,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number;
+            length: number | undefined;
         }>;
         principalId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "principal_id";
@@ -131,7 +131,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number;
+            length: number | undefined;
         }>;
         role: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "role";
@@ -150,7 +150,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number;
+            length: number | undefined;
         }>;
         createdBy: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "created_by";
@@ -169,7 +169,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number;
+            length: number | undefined;
         }>;
         createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "created_at";
@@ -188,7 +188,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: number;
+            length: number | undefined;
         }>;
     };
     dialect: "sqlite";

package/dist/styles/agent-conversation.css

@@ -454,3 +454,242 @@
     transform: rotate(360deg);
   }
 }
+
+/* ─── Agent-Markdown (AssistantChat react-markdown render surface) ─────────── */
+/* These classes are applied by the SmoothMarkdownText/MarkdownText components  */
+/* in the AssistantChat/AssistantChatInner tree. The shiki dual-theme rules      */
+/* follow the same .dark / @media pattern used above for agent-conversation.     */
+
+.agent-markdown > :first-child {
+  margin-top: 0;
+}
+
+.agent-markdown > :last-child {
+  margin-bottom: 0;
+}
+
+.agent-markdown p {
+  margin: 0.5em 0;
+}
+
+.agent-markdown ul,
+.agent-markdown ol {
+  margin: 0.5em 0;
+  padding-left: 1.5em;
+}
+
+.agent-markdown li {
+  margin: 0.2em 0;
+}
+
+.agent-markdown li > p {
+  margin: 0;
+}
+
+.agent-markdown h1 {
+  font-size: 1.25em;
+  font-weight: 600;
+  margin: 0.75em 0 0.25em;
+}
+
+.agent-markdown h2 {
+  font-size: 1.125em;
+  font-weight: 600;
+  margin: 0.75em 0 0.25em;
+}
+
+.agent-markdown h3 {
+  font-size: 1em;
+  font-weight: 600;
+  margin: 0.75em 0 0.25em;
+}
+
+.agent-markdown strong {
+  font-weight: 600;
+}
+
+.agent-markdown em {
+  font-style: italic;
+}
+
+.agent-markdown code {
+  font-size: 0.875em;
+  padding: 0.15em 0.35em;
+  border-radius: 0.25em;
+  background: hsl(var(--muted, 0 0% 15%));
+  color: hsl(var(--foreground, 0 0% 90%));
+  border: 1px solid hsl(var(--border, 0 0% 80%));
+}
+
+.agent-markdown pre {
+  margin: 0.5em 0;
+  padding: 0.75em 1em;
+  border-radius: 0.375em;
+  background: hsl(var(--muted, 0 0% 15%));
+  color: hsl(var(--foreground, 0 0% 90%));
+  overflow-x: auto;
+  border: 1px solid hsl(var(--border, 0 0% 80%));
+}
+
+.agent-markdown pre code {
+  padding: 0;
+  background: transparent;
+  font-size: 0.8125em;
+  color: inherit;
+  border: none;
+}
+
+.agent-markdown hr {
+  border: none;
+  border-top: 1px solid hsl(var(--border, 0 0% 20%));
+  margin: 0.75em 0 1em;
+}
+
+.agent-markdown a {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.agent-markdown a.agent-markdown-cta {
+  text-decoration: none;
+}
+
+.agent-markdown blockquote {
+  border-left: 2px solid hsl(var(--border, 0 0% 20%));
+  padding-left: 0.75em;
+  margin: 0.5em 0;
+  opacity: 0.8;
+}
+
+.agent-markdown table {
+  border-collapse: collapse;
+  margin: 0.5em 0;
+  font-size: 0.875em;
+}
+
+.agent-markdown th,
+.agent-markdown td {
+  border: 1px solid hsl(var(--border, 0 0% 20%));
+  padding: 0.35em 0.65em;
+  text-align: left;
+}
+
+.agent-markdown th {
+  font-weight: 600;
+  background: hsl(var(--muted, 0 0% 15%));
+  color: hsl(var(--foreground, 0 0% 90%));
+}
+
+/* Streaming caret appended after last non-code paragraph while text is live. */
+.agent-markdown[data-streaming="true"]
+  > :last-child:not(pre):not(table)::after {
+  content: "";
+  display: inline-block;
+  width: 0.42em;
+  height: 1em;
+  margin-left: 0.12em;
+  border-radius: 999px;
+  background: currentColor;
+  opacity: 0.35;
+  transform: translateY(0.16em);
+  animation: agent-markdown-stream-caret 1.15s ease-in-out infinite;
+}
+
+@keyframes agent-markdown-stream-caret {
+  0%,
+  100% {
+    opacity: 0.2;
+  }
+  50% {
+    opacity: 0.58;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .agent-markdown[data-streaming="true"]
+    > :last-child:not(pre):not(table)::after {
+    animation: none;
+    opacity: 0.28;
+  }
+}
+
+/* Shiki-highlighted code blocks inside agent-markdown replies. */
+.agent-markdown-shiki {
+  margin: 0.5em 0;
+  border-radius: 0.375em;
+  overflow: hidden;
+  font-size: 0.8125em;
+}
+
+.agent-markdown-shiki pre {
+  margin: 0;
+  padding: 0.75em 1em;
+  overflow-x: auto;
+  background: var(--shiki-light-bg);
+  color: var(--shiki-light);
+}
+
+.agent-markdown-shiki pre code {
+  background: transparent;
+  padding: 0;
+  font-size: inherit;
+  color: inherit;
+}
+
+.agent-markdown-shiki pre span {
+  color: var(--shiki-light);
+  background: var(--shiki-light-bg);
+}
+
+.dark .agent-markdown-shiki pre {
+  background: var(--shiki-dark-bg);
+  color: var(--shiki-dark);
+}
+
+.dark .agent-markdown-shiki pre span {
+  color: var(--shiki-dark);
+  background: var(--shiki-dark-bg);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not(.light) .agent-markdown-shiki pre {
+    background: var(--shiki-dark-bg);
+    color: var(--shiki-dark);
+  }
+
+  :root:not(.light) .agent-markdown-shiki pre span {
+    color: var(--shiki-dark);
+    background: var(--shiki-dark-bg);
+  }
+}
+
+/* Tool-code viewer that uses shiki inside the ToolDetailViewer. */
+.agent-tool-code .agent-markdown-shiki {
+  margin: 0;
+  border-radius: 0;
+  min-width: max-content;
+}
+
+.agent-tool-code .agent-markdown-shiki pre {
+  padding: 0.75rem;
+  border: 0;
+  background: transparent;
+}
+
+.agent-tool-code .agent-markdown-shiki pre span {
+  background: transparent;
+}
+
+.agent-tool-code pre {
+  margin: 0;
+  min-width: max-content;
+  padding: 0.75rem;
+  background: transparent;
+  color: inherit;
+}
+
+.agent-tool-code mark {
+  border-radius: 0.1875rem;
+  background: rgba(245, 158, 11, 0.25);
+  color: inherit;
+}

package/dist/templates/default/.agents/skills/delegate-to-agent/SKILL.md

@@ -13,7 +13,11 @@ metadata:
 
 ## Rule
 
-The UI and server never call an LLM directly. All AI work is delegated to the agent through the chat bridge.
+The UI never calls an LLM directly. Product workflows are delegated to the
+agent through the chat bridge so users can see, steer, and audit the work.
+Server-side one-shot model calls are an explicit escape hatch for narrow text
+transforms only; use `completeText()` from `@agent-native/core/server` when the
+work intentionally does not need tools, chat history, or run state.
 
 ## Why
 
@@ -33,6 +37,24 @@ sendToAgentChat({
 });
 ```
 
+**From the UI, in the background:**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core";
+
+sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+This is still a full agent run: tools, actions, thread state, and run tracking
+all remain active. It simply does not focus or open the sidebar.
+
 **From scripts (Node):**
 
 ```ts
@@ -41,6 +63,22 @@ import { agentChat } from "@agent-native/core";
 agentChat.submit("Process the uploaded images and create thumbnails");
 ```
 
+**For narrow server-side text transforms:**
+
+```ts
+import { completeText } from "@agent-native/core/server";
+
+const result = await completeText({
+  systemPrompt: "Return exactly one sentiment label.",
+  input: messageBody,
+  maxOutputTokens: 12,
+  temperature: 0,
+});
+```
+
+Wrap user-facing uses in actions so the UI and agent share the same operation.
+Do not call provider SDKs directly.
+
 **From the UI, detecting when agent is done:**
 
 ```ts
@@ -183,10 +221,20 @@ rather than ad-hoc LLM calls.
 - Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
 - Don't build "AI features" that bypass the agent chat
 - Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
+- Don't use `completeText()` for workflows that need tools, database writes,
+  auditability, user steering, or multi-step reasoning. Use the agent chat
+  instead, optionally with `background: true`.
 
 ## Exception
 
-Scripts may call external APIs (image generation, search, etc.) — but the AI reasoning and orchestration still goes through the agent. A script is a tool the agent uses, not a replacement for the agent.
+Scripts may call external APIs (image generation, search, etc.) — but the AI
+reasoning and orchestration still goes through the agent. A script is a tool
+the agent uses, not a replacement for the agent.
+
+`completeText()` is allowed for small server-side transforms such as
+classification, extraction, rewriting a short string, or normalizing messy
+provider text. It deliberately runs with `tools: []` and does not create chat
+thread state.
 
 ## When to Use A2A Instead
 

package/dist/templates/default/AGENTS.md

@@ -7,7 +7,7 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 ### Core Principles
 
 1. **Shared SQL database** -- All app state lives in SQL. Local SQLite at `data/app.db` is the zero-setup dev fallback; deployed apps need a persistent `DATABASE_URL` so data survives container/serverless restarts. Turso is optional, not required: Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments are all valid when supported by the deploy. Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
-2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`. Use `sendToAgentChat({ message, context, submit })` for simple UI handoffs and prefill/review flows. Only use the agent-chat context state helpers (`useAgentChatContext`, `setAgentChatContextItem`, `listAgentChatContext`, `removeAgentChatContextItem`, `clearAgentChatContext`) when the UI needs two-way sync with staged context chips.
+2. **AI through the right framework surface** -- Product workflows delegate to the agent via `sendToAgentChat()` / `agentChat.submit()`. Use `sendToAgentChat({ message, context, submit })` for simple UI handoffs and prefill/review flows; add `newTab: true, background: true, openSidebar: false` when the agent should work silently without focusing the sidebar. Only use the agent-chat context state helpers (`useAgentChatContext`, `setAgentChatContextItem`, `listAgentChatContext`, `removeAgentChatContextItem`, `clearAgentChatContext`) when the UI needs two-way sync with staged context chips. For rare server-side text transforms that intentionally need no tools, chat history, or run state, use `completeText()` from `@agent-native/core/server` inside an action instead of importing provider SDKs directly.
 3. **Actions for app operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`; `defineAction` also auto-exposes those operations at `/_agent-native/actions/:name` for the UI. Do not create custom REST routes that re-export actions.
 4. **Live sync keeps the UI current** -- Database writes stream over `/_agent-native/events` first, with `/_agent-native/poll` as the fallback. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` / `useActionMutation` for action-backed data (preferred). If you use raw `useQuery`, fold `useChangeVersions([<source>, "action"])` into the key for targeted refreshes. See the `real-time-sync` and `adding-a-feature` skills.
 5. **Agent can update code** -- The agent can modify this app's source code directly.