@sentropic/artifacts 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.2.7
+
+- Fix the `artifacts_get_source` wire payload that broke page editing in claude.ai:
+  files are no longer returned as a JSON integer array (`bytes: Array.from(bytes)`).
+  Text mime types (the canonical `TEXT_MIME_PATTERN`) come back as `text` with
+  `encoding: "utf8"`; every other file — including non-UTF-8 "text" — as `base64`
+  with `encoding: "base64"`. Size and digest verification still run on the raw
+  bytes before encoding. An 816-byte page now serializes to a few KiB instead of
+  blowing the tool-result budget.
+- `get_source` (and the conflict `currentSource`) no longer embeds any authoring
+  guide; the result carries only a `guideRef` (`{tool: "artifacts_get_api_guide",
+  version}`) naming the tool and version to fetch it from.
+- Per-call budgets are unchanged: at most 32 files and 262144 decoded bytes; the
+  2 MiB serialized MCP result budget still holds for the full snapshot.
+- Tool schema (`artifacts_get_source` description, v2 result schema source files),
+  the API guide text and the README source section describe the text/base64
+  encoding and the guide reference.
+
 ## 0.2.6
 
 - Integrate part 1 with the source reads, sharing, terminal deletion, masking and

package/README.md

@@ -439,9 +439,13 @@ empty defaults. Existing profile selections remain explicit.
 
 `POST /get_source` accepts `artifactId`, optional `releaseId`, and optional unique
 `paths` (1–32 entries). Bind `publication.getRelease` and `sources.getSource` on
-the HTTP app. It returns the canonical manifest, verified author file bytes,
-and separate nullable `sourceRef`; readers need the distinct source permission.
-The snapshot is limited to 32 files and 262144 decoded bytes. Hosts must qualify
+the HTTP app. It returns the canonical manifest, verified author files, and a
+separate nullable `sourceRef`; readers need the distinct source permission.
+Size and digest are verified on the raw bytes, then each file is encoded for the
+wire: text mime types as `text` with `encoding: "utf8"`, all other files as
+`base64` with `encoding: "base64"` — never an integer array. The result carries
+a `guideRef` (`{tool, version}`) instead of the guide body. The snapshot is
+limited to 32 files and 262144 decoded bytes. Hosts must qualify
 a 2 MiB serialized MCP result budget before selecting this capability.
 
 `POST /set_access` grants or revokes a named principal's read access, requires a

package/dist/http.d.ts

@@ -64,7 +64,7 @@ export interface ArtifactApp {
     handle(request: HttpRequest, invocation: ArtifactInvocationContext): Promise<HttpResponse>;
 }
 /** Retained for consumers describing canonical textual publication inputs. */
-export declare const TEXT_MIME_PATTERN = "^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])";
+export { TEXT_MIME_PATTERN } from './server/mime.js';
 /** Other mutation surfaces need their own qualification before host activation. */
 export declare function assertArtifactsTransportProfile(value: unknown): asserts value is CompiledArtifactsProfile;
 export declare function createHttpArtifactApp(deps: HttpAppDeps): ArtifactApp;

package/dist/http.js

@@ -15,6 +15,8 @@ import { artifactSummary } from './server/summary.js';
 import { artifactVersions } from './server/versions.js';
 import { manageArtifact } from './server/management.js';
 import { createPostgresManagementUnit } from './adapters/postgres-management.js';
+import { TEXT_MIME_RE } from './server/mime.js';
+import { API_GUIDE_REF } from './server/templates.js';
 export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 /** Stable content-route error codes; private driver messages never leave the host. */
 export function errorBody(status) {
@@ -23,8 +25,7 @@ export function errorBody(status) {
             500: 'internal_error', 503: 'capability_unavailable' }[status] ?? 'internal_error' };
 }
 /** Retained for consumers describing canonical textual publication inputs. */
-export const TEXT_MIME_PATTERN = '^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])';
-const TEXT_MIME_RE = new RegExp(TEXT_MIME_PATTERN);
+export { TEXT_MIME_PATTERN } from './server/mime.js';
 function object(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value))
         throw new ArtifactProfileInputError();
@@ -160,11 +161,13 @@ export function createHttpArtifactApp(deps) {
         const files = (await readManifestFiles(release.manifest, invocation.storageScopeId)).filter(file => paths.has(file.path))
             .map(file => ({ path: file.path, mimeType: file.mimeType, size: file.bytes.byteLength,
             digest: entries.find(entry => entry.path === file.path).digest,
-            ...(file.text === undefined ? { bytes: Array.from(file.bytes) } : { text: file.text }) }));
+            ...(file.text === undefined
+                ? { base64: Buffer.from(file.bytes).toString('base64'), encoding: 'base64' }
+                : { text: file.text, encoding: 'utf8' }) }));
         await visible(artifactId, invocation, 'source');
         const failure = { ...outcome.failure, conflict: { ...conflict, currentSource: {
                     artifactId, releaseId: release.releaseId, digest: conflict.currentDigest, manifest: release.manifest,
-                    files, sourceRef: null, ...deps.publicationUrls?.(artifactId, release.releaseId),
+                    files, sourceRef: null, guideRef: API_GUIDE_REF, ...deps.publicationUrls?.(artifactId, release.releaseId),
                 } } };
         Object.defineProperty(failure, 'cause', { value: outcome.failure.cause, enumerable: false });
         return { ok: false, failure: Object.freeze(failure) };

package/dist/mcp-core.d.ts

@@ -10,7 +10,7 @@ export { createRadarKeyDerivation } from './server/command-identity.js';
 export type { ArtifactKeyDerivationBinding } from './server/command-identity.js';
 export declare const ARTIFACTS_PROVIDER_ID = "sentropic.artifacts";
 export declare const ARTIFACTS_APP_ID = "sentropic-artifacts";
-export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.6";
+export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.7";
 export declare const ARTIFACTS_TOOL_NAMES: readonly ["artifacts_get_template", "artifacts_get_api_guide", "artifacts_ensure", "artifacts_publish", "artifacts_create_upload", "artifacts_commit_upload", "artifacts_list", "artifacts_get", "artifacts_get_source", "artifacts_fork", "artifacts_set_access", "artifacts_promote", "artifacts_renew", "artifacts_delete", "artifacts_restore", "artifacts_list_versions", "artifacts_revert"];
 export type ArtifactsToolName = (typeof ARTIFACTS_TOOL_NAMES)[number];
 export declare const ARTIFACTS_TOOL_SPECS: {

package/dist/mcp-core.js

@@ -7,10 +7,13 @@ export * from './profile/index.js';
 export { createRadarKeyDerivation } from './server/command-identity.js';
 export const ARTIFACTS_PROVIDER_ID = 'sentropic.artifacts';
 export const ARTIFACTS_APP_ID = 'sentropic-artifacts';
-export const ARTIFACTS_PROVIDER_VERSION = '0.2.6';
+export const ARTIFACTS_PROVIDER_VERSION = '0.2.7';
 export const ARTIFACTS_TOOL_NAMES = ARTIFACT_CAPABILITY_NAMES;
 export const ARTIFACTS_TOOL_SPECS = ARTIFACTS_TOOL_NAMES.map((name) => ({ name,
-    description: `Artifacts ${name.slice('artifacts_'.length).replaceAll('_', ' ')}.`,
+    description: name === 'artifacts_get_source'
+        ? 'Artifacts get source: verified files of the current or a selected release as `text` (encoding "utf8") '
+            + 'or `base64` (encoding "base64"), never an integer array, plus a guideRef instead of the guide body.'
+        : `Artifacts ${name.slice('artifacts_'.length).replaceAll('_', ' ')}.`,
     mutability: (['artifacts_list', 'artifacts_get', 'artifacts_get_template', 'artifacts_get_api_guide',
         'artifacts_get_source', 'artifacts_list_versions'].includes(name) ? 'read-only' : name === 'artifacts_publish' ? 'append' : 'state-transition'),
 }));

package/dist/profile/schemas.js

@@ -86,7 +86,10 @@ export function capabilitySchema(name, profile) {
         case 'list_versions': return profile.resultEnvelopeVersion !== 2 ? idOnly : obj({ artifactId: id,
             limit: { ...integer(1, 100), default: 20 }, cursor: { ...str, maxLength: 4096 } }, ['artifactId']);
         case 'get_source': return obj({ artifactId: id, releaseId: id,
-            paths: { type: 'array', minItems: 1, maxItems: 32, items: { ...str, maxLength: profile.rules.pathMaxBytes } } }, ['artifactId']);
+            paths: { type: 'array', minItems: 1, maxItems: 32, items: { ...str, maxLength: profile.rules.pathMaxBytes },
+                description: 'Unique manifest paths; omit to read the whole snapshot (max 32 files, 256 KiB decoded). ' +
+                    'Result files are `text` with encoding "utf8" or `base64` with encoding "base64" (never an integer ' +
+                    'array), plus a guideRef; the guide body is never embedded.' } }, ['artifactId']);
         case 'delete': return obj({ artifactId: id, expectedCurrentReleaseId: { ...id, type: ['string', 'null'] },
             idempotencyKey: key, confirmationRef: { ...str, maxLength: 4096 } }, ['artifactId', 'idempotencyKey', ...(profile.requireExpectedCurrentReleaseId ? ['expectedCurrentReleaseId'] : [])]);
         case 'revert': {

package/dist/server/mime.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Canonical text-mime pattern shared by publication input rules and source
+ * reads. Leaf module: both `http.ts` and `server/source-read.ts` import it
+ * without an import cycle.
+ */
+export declare const TEXT_MIME_PATTERN = "^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])";
+export declare const TEXT_MIME_RE: RegExp;

package/dist/server/mime.js

@@ -0,0 +1,7 @@
+/**
+ * Canonical text-mime pattern shared by publication input rules and source
+ * reads. Leaf module: both `http.ts` and `server/source-read.ts` import it
+ * without an import cycle.
+ */
+export const TEXT_MIME_PATTERN = '^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])';
+export const TEXT_MIME_RE = new RegExp(TEXT_MIME_PATTERN);

package/dist/server/result-schema.js

@@ -7,11 +7,19 @@ const object = (properties, required = Object.keys(properties)) => ({
 const error = (code, details) => object({
     code: { enum: [code] }, message: string, retriable: { type: 'boolean' }, details,
 });
+/** get_source file: verified raw bytes encoded as UTF-8 text or base64, never an integer array. */
+const sourceFile = { type: 'object', additionalProperties: false,
+    properties: { path: string, mimeType: string, size: { type: 'integer', minimum: 0 }, digest: string,
+        encoding: { enum: ['utf8', 'base64'] }, text: string, base64: string },
+    required: ['path', 'mimeType', 'size', 'digest', 'encoding'],
+    oneOf: [{ required: ['text'], not: { required: ['base64'] } },
+        { required: ['base64'], not: { required: ['text'] } }] };
+const guideRef = object({ tool: string, version: string }, ['tool', 'version']);
 const pointer = object({ variant: { enum: ['pointer_conflict'] }, artifactId: string,
     expectedCurrentReleaseId: nullable, currentReleaseId: nullable, currentDigest: nullable,
     currentSource: object({ artifactId: string, releaseId: string, digest: nullable,
-        manifest: string, files: { type: 'array', items: { type: 'object' } }, sourceRef: { type: ['object', 'null'] },
-        stableUrl: string, pinnedUrl: string }, ['artifactId', 'releaseId', 'digest', 'manifest', 'files', 'sourceRef']),
+        manifest: string, files: { type: 'array', items: sourceFile }, sourceRef: { type: ['object', 'null'] },
+        guideRef, stableUrl: string, pinnedUrl: string }, ['artifactId', 'releaseId', 'digest', 'manifest', 'files', 'sourceRef', 'guideRef']),
 }, ['variant', 'artifactId', 'expectedCurrentReleaseId', 'currentReleaseId', 'currentDigest']);
 const common = { invocationId: string,
     commitState: { enum: ['not_committed', 'committed', 'unknown'] } };

package/dist/server/source-read.d.ts

@@ -11,6 +11,11 @@ export interface SourceReadPorts {
         stableUrl: string;
         pinnedUrl: string;
     };
+    /** Guide reference returned instead of embedding the guide body. */
+    guideRef?: {
+        tool: string;
+        version: string;
+    };
     maxFiles: number;
     maxTotalBytes: number;
 }
@@ -27,12 +32,27 @@ export declare function readArtifactSource(ports: SourceReadPorts, input: Source
     releaseId: string;
     digest: string;
     manifest: string;
-    files: {
-        bytes: number[];
+    files: ({
+        text: string;
+        encoding: "utf8";
+        path: string;
+        mimeType: string;
+        digest: string;
+        size: number;
+    } | {
+        base64: string;
+        encoding: "base64";
         path: string;
         mimeType: string;
         digest: string;
         size: number;
-    }[];
+    })[];
     sourceRef: SourceRef | null;
+    guideRef: {
+        readonly tool: "artifacts_get_api_guide";
+        readonly version: "v1";
+    } | {
+        tool: string;
+        version: string;
+    };
 }>;

package/dist/server/source-read.js

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto';
 import { parseManifest } from '../codecs.js';
 import { ArtifactOperationError } from './failures.js';
+import { TEXT_MIME_RE } from './mime.js';
+import { API_GUIDE_REF } from './templates.js';
 /** Read author bytes only. Provenance never substitutes for a stored snapshot. */
 export async function readArtifactSource(ports, input) {
     await ports.authorize();
@@ -59,10 +61,23 @@ export async function readArtifactSource(ports, input) {
             createHash('sha256').update(bytes).digest('hex') !== file.digest.slice(7)) {
             throw new ArtifactOperationError('verification_failed');
         }
-        files.push({ ...file, bytes: Array.from(bytes) });
+        // Verified raw bytes are encoded for the wire: text mime types as UTF-8
+        // text, everything else (including non-UTF-8 "text") as base64. Never an
+        // integer array, which blows the tool-result budget on small pages.
+        let text;
+        if (TEXT_MIME_RE.test(file.mimeType)) {
+            try {
+                text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch { /* Not valid UTF-8: fall back to base64. */ }
+        }
+        files.push({ ...file, ...(text !== undefined
+                ? { text, encoding: 'utf8' }
+                : { base64: Buffer.from(bytes).toString('base64'), encoding: 'base64' }) });
     }
     const sourceRef = await ports.getSource(input.artifactId) ?? null;
     await ports.authorize();
     return { artifactId: input.artifactId, releaseId: release.releaseId, digest: manifest.digest,
-        manifest: release.manifest, files, sourceRef, ...ports.urls?.(input.artifactId, release.releaseId) };
+        manifest: release.manifest, files, sourceRef, guideRef: ports.guideRef ?? API_GUIDE_REF,
+        ...ports.urls?.(input.artifactId, release.releaseId) };
 }

package/dist/server/templates.d.ts

@@ -29,5 +29,10 @@ export interface TemplateCatalogPort {
 }
 export declare const DEFAULT_TEMPLATE_ID = "static-html";
 export declare const DEFAULT_API_GUIDE_VERSION = "v1";
+/** Wire reference returned by get_source instead of embedding the guide body. */
+export declare const API_GUIDE_REF: {
+    readonly tool: "artifacts_get_api_guide";
+    readonly version: "v1";
+};
 /** Generic in-package catalog; hosts override with approved local assets. */
 export declare function createDefaultTemplateCatalog(): TemplateCatalogPort;

package/dist/server/templates.js

@@ -9,6 +9,8 @@
  */
 export const DEFAULT_TEMPLATE_ID = 'static-html';
 export const DEFAULT_API_GUIDE_VERSION = 'v1';
+/** Wire reference returned by get_source instead of embedding the guide body. */
+export const API_GUIDE_REF = { tool: 'artifacts_get_api_guide', version: DEFAULT_API_GUIDE_VERSION };
 const INDEX_HTML = [
     '<!doctype html>',
     '<html lang="en">',
@@ -66,7 +68,11 @@ const GUIDE_V1 = [
     '- `artifacts_list_versions`: full release history of one artifact —',
     '  per release: id, created at, author, state, whether it is current,',
     '  and a content digest.',
-    '- `artifacts_get_source`: current file contents (text decoded) for editing.',
+    '- `artifacts_get_source`: verified file contents of the current or a selected',
+    '  release, for editing. Text mime types come back as `text` with',
+    '  `encoding: "utf8"`; every other file as `base64` with `encoding: "base64"` —',
+    '  never an integer array. The result carries a `guideRef` (tool + version),',
+    '  never the guide body. Per call: at most 32 files and 256 KiB decoded.',
     '- `artifacts_revert`: make an earlier release current again as a NEW',
     '  release that copies its content — the artifact URL stays stable and',
     '  history only grows. Purged releases are refused with `release_unavailable`.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/artifacts",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Generic configurable artifacts MCP and artifact service: StorageScope/Artifact/Binding/Release model, canonical manifests, object authorization, idempotent intents (spec-v8 §9).",
   "type": "module",
   "license": "MIT",