refactor(runtime): persist durable Tool Result projections

apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-visibility.ts

@@ -17,28 +17,10 @@
  * under the License.
  */
 
-import type { ArtifactDescriptor, ArtifactSource } from '@maka/core/artifacts';
-
-const USER_VISIBLE_ARTIFACT_SOURCES = {
-  tool_result: false,
-  tool_result_archive: false,
-  synthesis_cache_block: false,
-  history_compact_block: false,
-  history_compact_source: false,
-  provider_request_capture: false,
-  session_effect: false,
-  subagent_writeback: true,
-  deep_research: true,
-  user_upload: false,
-  export: true,
-  snapshot: true,
-  fixture: true,
-} satisfies Record<ArtifactSource, boolean>;
+import { isArtifactUserVisible, type ArtifactDescriptor } from '@maka/core/artifacts';
 
 export function filterUserVisibleArtifacts(
   records: readonly ArtifactDescriptor[],
 ): ArtifactDescriptor[] {
-  return records.filter(
-    (record) => record.source === undefined || USER_VISIBLE_ARTIFACT_SOURCES[record.source],
-  );
+  return records.filter(isArtifactUserVisible);
 }

packages/core/package.json

@@ -7,6 +7,7 @@
   "sideEffects": false,
   "private": true,
   "exports": {
+    "./durable-tool-result-projection": "./dist/durable-tool-result-projection.js",
     "./canonical-runtime-event": "./dist/canonical-runtime-event.js",
     "./runtime-boundary": "./dist/runtime-boundary.js",
     "./runtime-event": "./dist/runtime-event.js",

packages/core/src/__tests__/artifacts.test.ts

@@ -23,6 +23,8 @@ import {
   ARTIFACT_ENTITY_ID_MAX_CHARS,
   ARTIFACT_TURN_KEY_MAX_CHARS,
   canUserDeleteArtifact,
+  isArtifactSharedSessionReadable,
+  isArtifactUserVisible,
   isArtifactTurnKey,
   isCanonicalArtifactEntityId,
 } from '../artifacts.js';
@@ -61,3 +63,21 @@ describe('Artifact user-delete policy', () => {
     assert.equal(canUserDeleteArtifact({ source: undefined }), true);
   });
 });
+
+describe('Artifact source policy', () => {
+  test('keeps projection artifacts internal, durable, and readable in shared sessions', () => {
+    const projection = { source: 'tool_result_projection' as const };
+
+    assert.equal(canUserDeleteArtifact(projection), false);
+    assert.equal(isArtifactUserVisible(projection), false);
+    assert.equal(isArtifactSharedSessionReadable(projection), true);
+  });
+
+  test('preserves unattributed artifact defaults', () => {
+    const unattributed = { source: undefined };
+
+    assert.equal(canUserDeleteArtifact(unattributed), true);
+    assert.equal(isArtifactUserVisible(unattributed), true);
+    assert.equal(isArtifactSharedSessionReadable(unattributed), false);
+  });
+});

packages/core/src/__tests__/durable-tool-result-projection.test.ts

@@ -0,0 +1,160 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  decodeDurableToolResultProjection,
+  DURABLE_TOOL_RESULT_PROJECTION_MAX_BYTES,
+  DURABLE_TOOL_RESULT_PROJECTION_MAX_JSON_DEPTH,
+  DURABLE_TOOL_RESULT_PROJECTION_MAX_JSON_NODES,
+} from '../durable-tool-result-projection.js';
+
+describe('durable Tool Result projection', () => {
+  it('accepts only the closed current-version schema', () => {
+    const projection = { version: 1, kind: 'text', text: 'safe' } as const;
+
+    assert.deepEqual(decodeDurableToolResultProjection(projection), projection);
+    assert.throws(
+      () => decodeDurableToolResultProjection({ ...projection, version: 2 }),
+      /Invalid durable Tool Result projection/,
+    );
+    assert.throws(
+      () => decodeDurableToolResultProjection({ ...projection, providerOptions: {} }),
+      /Invalid durable Tool Result projection/,
+    );
+    assert.throws(
+      () =>
+        decodeDurableToolResultProjection({
+          version: 1,
+          kind: 'content',
+          parts: [],
+        }),
+      /Invalid durable Tool Result projection/,
+    );
+  });
+
+  it('rejects projections whose serialized JSON exceeds the durable byte bound', () => {
+    assert.throws(
+      () =>
+        decodeDurableToolResultProjection({
+          version: 1,
+          kind: 'text',
+          text: 'x'.repeat(DURABLE_TOOL_RESULT_PROJECTION_MAX_BYTES),
+        }),
+      /Invalid durable Tool Result projection/,
+    );
+  });
+
+  it('accepts only content-addressed references owned by the same Session protocol', () => {
+    assert.deepEqual(
+      decodeDurableToolResultProjection({
+        version: 1,
+        kind: 'content',
+        parts: [
+          {
+            kind: 'artifact',
+            mediaType: 'image/png',
+            ref: { kind: 'session_context', sessionId: 'session-1', refId: 'sha256-image' },
+          },
+        ],
+      }).kind,
+      'content',
+    );
+    assert.throws(
+      () =>
+        decodeDurableToolResultProjection({
+          version: 1,
+          kind: 'content',
+          parts: [
+            {
+              kind: 'artifact',
+              mediaType: 'image/png',
+              ref: { kind: 'external_file', absolutePath: '/private/image.png' },
+            },
+          ],
+        }),
+      /Invalid durable Tool Result projection/,
+    );
+    assert.throws(
+      () =>
+        decodeDurableToolResultProjection({
+          version: 1,
+          kind: 'content',
+          parts: [
+            {
+              kind: 'artifact',
+              mediaType: 'image/png',
+              ref: {
+                kind: 'session_file',
+                sessionId: 'session-1',
+                relativePath: 'arbitrary/path.png',
+              },
+            },
+          ],
+        }),
+      /Invalid durable Tool Result projection/,
+    );
+  });
+
+  it('admits only canonical safe image media types', () => {
+    const projection = (mediaType: string) => ({
+      version: 1,
+      kind: 'content',
+      parts: [
+        {
+          kind: 'artifact',
+          mediaType,
+          ref: { kind: 'session_file', sessionId: 'session-1', relativePath: 'artifact-1' },
+        },
+      ],
+    });
+
+    assert.equal(decodeDurableToolResultProjection(projection('image/png')).kind, 'content');
+    assert.throws(
+      () => decodeDurableToolResultProjection(projection('image/png; token=sk-secret')),
+      /Invalid durable Tool Result projection/,
+    );
+    assert.throws(
+      () => decodeDurableToolResultProjection(projection('image/svg+xml')),
+      /Invalid durable Tool Result projection/,
+    );
+  });
+
+  it('applies the same bounded JSON budget to persisted projections', () => {
+    let tooDeep: unknown = 'leaf';
+    for (let depth = 0; depth <= DURABLE_TOOL_RESULT_PROJECTION_MAX_JSON_DEPTH; depth += 1) {
+      tooDeep = [tooDeep];
+    }
+    assert.throws(
+      () => decodeDurableToolResultProjection({ version: 1, kind: 'json', value: tooDeep }),
+      /Invalid durable Tool Result projection/,
+    );
+    assert.throws(
+      () =>
+        decodeDurableToolResultProjection({
+          version: 1,
+          kind: 'json',
+          value: Array.from({ length: DURABLE_TOOL_RESULT_PROJECTION_MAX_JSON_NODES }, () => null),
+        }),
+      /Invalid durable Tool Result projection/,
+    );
+  });
+});

packages/core/src/__tests__/runtime-event.test.ts

@@ -498,6 +498,40 @@ describe('RuntimeEvent content variants', () => {
   });
 });
 
+test('rejects a Tool Result projection that references another Session artifact', () => {
+  assert.throws(
+    () =>
+      decodeRuntimeEvent(
+        baseEvent({
+          role: 'tool',
+          author: 'tool',
+          content: {
+            kind: 'function_response',
+            id: 'call-1',
+            name: 'Read',
+            result: { kind: 'image' },
+            modelProjection: {
+              version: 1,
+              kind: 'content',
+              parts: [
+                {
+                  kind: 'artifact',
+                  mediaType: 'image/png',
+                  ref: {
+                    kind: 'session_context',
+                    sessionId: 'another-session',
+                    refId: 'image-1',
+                  },
+                },
+              ],
+            },
+          },
+        }),
+      ),
+    /Invalid RuntimeEvent schema/,
+  );
+});
+
 describe('RuntimeEvent actions', () => {
   test('binds the managed mutation digest to its canonical execution semantics', () => {
     const canonicalProfile = JSON.stringify({

packages/core/src/artifacts.ts

@@ -88,6 +88,7 @@ export function resolveArtifactImagePreview(
 
 export const ARTIFACT_SOURCES = [
   'tool_result',
+  'tool_result_projection',
   'tool_result_archive',
   'synthesis_cache_block',
   'history_compact_block',
@@ -152,24 +153,39 @@ export interface ArtifactRecord extends ArtifactDescriptor {
   deepResearchRole?: import('./deep-research-run.js').DeepResearchArtifactRole;
 }
 
-const ARTIFACT_USER_DELETE_ALLOWED_BY_SOURCE = {
-  tool_result: true,
-  tool_result_archive: false,
-  synthesis_cache_block: true,
-  history_compact_block: true,
-  history_compact_source: true,
-  provider_request_capture: true,
-  subagent_writeback: false,
-  deep_research: false,
-  user_upload: true,
-  export: true,
-  snapshot: true,
-  session_effect: false,
-  fixture: true,
-} as const satisfies Record<ArtifactSource, boolean>;
+interface ArtifactSourcePolicy {
+  readonly userDeletable: boolean;
+  readonly userVisible: boolean;
+  readonly sharedReadable: boolean;
+}
+
+const ARTIFACT_SOURCE_POLICIES = {
+  tool_result: { userDeletable: true, userVisible: false, sharedReadable: true },
+  tool_result_projection: { userDeletable: false, userVisible: false, sharedReadable: true },
+  tool_result_archive: { userDeletable: false, userVisible: false, sharedReadable: false },
+  synthesis_cache_block: { userDeletable: true, userVisible: false, sharedReadable: false },
+  history_compact_block: { userDeletable: true, userVisible: false, sharedReadable: false },
+  history_compact_source: { userDeletable: true, userVisible: false, sharedReadable: false },
+  provider_request_capture: { userDeletable: true, userVisible: false, sharedReadable: false },
+  subagent_writeback: { userDeletable: false, userVisible: true, sharedReadable: false },
+  deep_research: { userDeletable: false, userVisible: true, sharedReadable: false },
+  user_upload: { userDeletable: true, userVisible: false, sharedReadable: true },
+  export: { userDeletable: true, userVisible: true, sharedReadable: false },
+  snapshot: { userDeletable: true, userVisible: true, sharedReadable: false },
+  session_effect: { userDeletable: false, userVisible: false, sharedReadable: false },
+  fixture: { userDeletable: true, userVisible: true, sharedReadable: false },
+} as const satisfies Record<ArtifactSource, ArtifactSourcePolicy>;
 
 export function canUserDeleteArtifact(record: Pick<ArtifactRecord, 'source'>): boolean {
-  return record.source === undefined || ARTIFACT_USER_DELETE_ALLOWED_BY_SOURCE[record.source];
+  return record.source === undefined || ARTIFACT_SOURCE_POLICIES[record.source].userDeletable;
+}
+
+export function isArtifactUserVisible(record: Pick<ArtifactRecord, 'source'>): boolean {
+  return record.source === undefined || ARTIFACT_SOURCE_POLICIES[record.source].userVisible;
+}
+
+export function isArtifactSharedSessionReadable(record: Pick<ArtifactRecord, 'source'>): boolean {
+  return record.source !== undefined && ARTIFACT_SOURCE_POLICIES[record.source].sharedReadable;
 }
 
 export type ArtifactChangedReason = 'created' | 'deleted' | 'purged';