maka-agent 0.2.1-dev.84.20261014 → 0.2.1-dev.86.20261014

package/dist/acp/session-configuration.js

@@ -28,6 +28,7 @@ const PERMISSION_NAMES = {
 const THINKING_NAMES = {
     default: 'Default',
     off: 'Off',
+    on: 'On',
     minimal: 'Minimal',
     low: 'Low',
     medium: 'Medium',

package/dist/run-command-core.js

@@ -117,14 +117,13 @@ export function parseMakaRunArgs(argv) {
             ...(flags.get('cwd') !== undefined ? { cwd: flags.get('cwd') } : {}),
             ...(flags.get('connection') !== undefined ? { connection: flags.get('connection') } : {}),
             ...(flags.get('model') !== undefined ? { model: flags.get('model') } : {}),
-            ...(thinking !== undefined && thinking !== 'default' ? { thinking } : {}),
+            ...(thinking !== undefined ? { thinking: thinking === 'default' ? null : thinking } : {}),
             ...(timeoutSeconds !== undefined ? { timeoutMs: Math.ceil(timeoutSeconds * 1_000) } : {}),
             ...(parsedMaxSteps !== undefined ? { maxSteps: parsedMaxSteps } : {}),
             ...(booleanFlags.has('yolo') ? { yolo: true } : {}),
             ...(resumeId !== undefined ? { resumeId } : {}),
             ...(continueLatest ? { continueLatest: true } : {}),
             ...(graph ? { graph: true } : {}),
-            ...(thinking === 'default' ? { thinkingDefaultExplicit: true } : {}),
             ...(flags.get('host') !== undefined ? { hostProfileId: flags.get('host') } : {}),
             ...(flags.get('project') !== undefined ? { projectId: flags.get('project') } : {}),
         },
@@ -159,10 +158,8 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
                 ? { explicitConnection: parsed.options.connection }
                 : {}),
             ...(parsed.options.model !== undefined ? { explicitModel: parsed.options.model } : {}),
-            thinkingSpecified: parsed.options.thinking !== undefined || parsed.options.thinkingDefaultExplicit === true,
-            ...(parsed.options.thinking !== undefined
-                ? { explicitThinking: parsed.options.thinking }
-                : {}),
+            thinkingSpecified: parsed.options.thinking !== undefined,
+            ...(parsed.options.thinking != null ? { explicitThinking: parsed.options.thinking } : {}),
         }, {
             canonicalizeDirectory: canonicalDirectory,
             ...(parsed.options.hostProfileId && parsed.options.hostProfileId !== 'local'
@@ -381,7 +378,7 @@ function makaRunHelpText(cliCommand) {
         '  --host <profile-id>       Connect through a saved Runtime Host profile',
         '  --project <project-id>    Select an existing Project on a remote Host',
         '  --model <id>              Model to use',
-        '  --thinking <level>        off|minimal|low|medium|high|xhigh|max|default',
+        '  --thinking <level>        off|on|minimal|low|medium|high|xhigh|max|default',
         '  --timeout <seconds>       Invocation timeout',
         '  --max-steps <count>       Tool-step cap',
         '  --yolo                    Give this task full access to your files and network',

package/dist/runtime-host-session-driver.js

@@ -159,12 +159,12 @@ class RuntimeHostMakaSessionDriverImpl {
             this.#llmConnectionId = input.llmConnectionId;
         this.#llmConnectionSlug = input.llmConnectionSlug;
         this.#model = input.model;
-        this.#thinkingLevel = input.thinkingLevel;
+        this.#thinkingLevel = input.thinkingLevel ?? undefined;
         // An omitted mode stays omitted: the Host applies its configured default.
         // Substituting a literal `ask` here would make the CLI a second authority
         // over the starting boundary and silently override that default.
         this.#permissionMode = input.permissionMode;
-        const session = await this.#createSession(input.name ?? DEFAULT_SESSION_NAME);
+        const session = await this.#createSession(input.name ?? DEFAULT_SESSION_NAME, input.thinkingLevel);
         return projectSessionCatalogSummary(session);
     }
     async listSessions(options = {}) {
@@ -1139,7 +1139,7 @@ class RuntimeHostMakaSessionDriverImpl {
                 this.#sessionCreation = undefined;
         }
     }
-    async #createSession(name) {
+    async #createSession(name, thinkingLevel = this.#thinkingLevel) {
         const workspace = this.#workspace.target;
         if (!workspace) {
             throw new Error('A remote Runtime Host Session requires an explicit Project');
@@ -1163,7 +1163,7 @@ class RuntimeHostMakaSessionDriverImpl {
             ...(this.#orchestrationMode === 'default'
                 ? {}
                 : { orchestrationMode: this.#orchestrationMode }),
-            ...(this.#thinkingLevel === undefined ? {} : { thinkingLevel: this.#thinkingLevel }),
+            ...(thinkingLevel === undefined ? {} : { thinkingLevel }),
         }));
         this.#sessionGeneration += 1;
         this.#sessionId = sessionId;

package/dist/tui-copy-catalog.js

@@ -178,6 +178,7 @@ const TUI_COPY_RESOURCES_PICKERS_EN = {
     addAccount: 'add account',
     thinkingLevels: {
         off: 'Off',
+        on: 'On',
         minimal: 'Minimal',
         low: 'Low',
         medium: 'Medium',
@@ -921,6 +922,7 @@ export const TUI_COPY_RESOURCES = {
             addAccount: '添加账号',
             thinkingLevels: {
                 off: '关',
+                on: '开',
                 minimal: '最小',
                 low: '低',
                 medium: '中',
@@ -1045,6 +1047,7 @@ export const TUI_COPY_RESOURCES = {
             addAccount: '新增帳號',
             thinkingLevels: {
                 off: '關',
+                on: '開',
                 minimal: '最小',
                 low: '低',
                 medium: '中',

package/node_modules/@maka/antigravity-acp-plugin/dist/plugin.mjs

@@ -1,6 +1,7 @@
 // ../core/dist/model-thinking.js
 var THINKING_LEVELS = [
   "off",
+  "on",
   "minimal",
   "low",
   "medium",
@@ -8,7 +9,7 @@ var THINKING_LEVELS = [
   "xhigh",
   "max"
 ];
-var DECLARABLE_RELAY_THINKING_LEVELS = THINKING_LEVELS.filter((level) => level !== "off");
+var DECLARABLE_RELAY_THINKING_LEVELS = THINKING_LEVELS.filter((level) => level !== "off" && level !== "on");
 
 // src/model-presentation.ts
 function describeAntigravityModels(models) {

package/node_modules/@maka/core/dist/image-delivery.js

@@ -0,0 +1,83 @@
+/*
+ * 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.
+ */
+/** Client-safe delivery contract. No filesystem or networking capabilities live here. */
+export const IMAGE_DELIVERY_IDENTITY_MAX_LENGTH = 512;
+export const IMAGE_DELIVERY_SOURCE_MAX_LENGTH = 4096;
+/** JavaScript string length, shared by stream capture and Markdown consumers. */
+export const IMAGE_MARKDOWN_MAX_LENGTH = 1024 * 1024;
+export function isImageDeliverySource(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= IMAGE_DELIVERY_SOURCE_MAX_LENGTH &&
+        !/[\x00-\x1f\x7f]/.test(value));
+}
+export function isRemoteImageSource(source) {
+    return /^https?:/i.test(source);
+}
+export function isImageDeliveryRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const v = value;
+    const identity = (s) => typeof s === 'string' &&
+        s.length > 0 &&
+        s.length <= IMAGE_DELIVERY_IDENTITY_MAX_LENGTH &&
+        !/[\x00-\x1f\x7f]/.test(s);
+    return (Object.keys(v).every((k) => ['turnId', 'messageId', 'source', 'retry', 'loadRemote'].includes(k)) &&
+        identity(v.turnId) &&
+        identity(v.messageId) &&
+        isImageDeliverySource(v.source) &&
+        (v.retry === undefined || typeof v.retry === 'boolean') &&
+        (v.loadRemote === undefined || typeof v.loadRemote === 'boolean'));
+}
+export const IMAGE_DELIVERY_FAILURES = [
+    'not_found',
+    'not_allowed',
+    'too_large',
+    'unsupported_mime',
+    'quota_exceeded',
+    'download_failed',
+    'read_failed',
+    'queue_full',
+];
+export function isImageDeliveryAttempt(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const v = value;
+    return (Object.keys(v).every((k) => ['status', 'reason'].includes(k)) &&
+        (v.status === 'pending'
+            ? v.reason === undefined
+            : v.status === 'failed' && IMAGE_DELIVERY_FAILURES.includes(v.reason)));
+}
+export const DEFAULT_IMAGE_ARCHIVE_LIMITS = Object.freeze({
+    sessionBytes: 100 * 1024 * 1024,
+    workspaceBytes: 1024 * 1024 * 1024,
+});
+export function isImageDeliveryMetadata(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const v = value;
+    return (Object.keys(v).every((k) => ['messageId', 'source', 'status', 'contentSha256'].includes(k)) &&
+        typeof v.messageId === 'string' &&
+        v.messageId.length > 0 &&
+        v.messageId.length <= IMAGE_DELIVERY_IDENTITY_MAX_LENGTH &&
+        isImageDeliverySource(v.source) &&
+        v.status === 'ready' &&
+        typeof v.contentSha256 === 'string' &&
+        /^[a-f0-9]{64}$/.test(v.contentSha256));
+}

package/node_modules/@maka/core/dist/image-markdown.js

@@ -0,0 +1,44 @@
+/*
+ * 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 { Lexer, Marked } from 'marked';
+import { IMAGE_MARKDOWN_MAX_LENGTH } from './image-delivery.js';
+const parser = new Marked({ gfm: true });
+/** Canonical image destinations in real Markdown nodes, including attachment refs.
+ * Consumers own their source policy; parsing grants no filesystem or network access.
+ */
+export function markdownImageSources(text) {
+    return [...new Set(markdownImages(text).map((image) => image.source))];
+}
+/** Original token spelling and canonical destination, including reference images. */
+export function markdownImages(text) {
+    if (!text.includes('![') || text.length > IMAGE_MARKDOWN_MAX_LENGTH)
+        return [];
+    const images = [];
+    parser.walkTokens(parser.lexer(text), (token) => {
+        if (token.type === 'image')
+            images.push({ raw: token.raw, source: token.href });
+    });
+    return images;
+}
+/** Resolve a complete inline destination, rejecting trailing or partial syntax. */
+export function parseMarkdownImageDestination(source) {
+    const markdown = `![](${source})`;
+    const [token] = Lexer.lexInline(markdown, { gfm: true });
+    return token?.type === 'image' && token.raw === markdown ? token.href : undefined;
+}

package/node_modules/@maka/core/dist/model-metadata.js

@@ -439,6 +439,14 @@ const COMMAND_CODE_MODEL_METADATA = {
 function buildStaticModelMetadata(active) {
     return {
         anthropic: ANTHROPIC_MODEL_OVERRIDES,
+        opencode: {
+            'claude-sonnet-4-5': {
+                thinkingOptions: ANTHROPIC_MODEL_OVERRIDES['claude-sonnet-4-5'].thinkingOptions,
+            },
+            'claude-haiku-4-5': {
+                thinkingOptions: ANTHROPIC_MODEL_OVERRIDES['claude-haiku-4-5'].thinkingOptions,
+            },
+        },
         openai: OPENAI_GPT6_MODEL_OVERRIDES,
         'claude-subscription': claudeSubscriptionModelMetadata(active),
         // The Command Code Provider-API plan rides the same effort table.

package/node_modules/@maka/core/dist/model-thinking.js

@@ -20,6 +20,7 @@ import { lookupModelMetadata } from './model-metadata.js';
 import { isModelApiProtocol } from './provider-registry.js';
 export const THINKING_LEVELS = [
     'off',
+    'on',
     'minimal',
     'low',
     'medium',
@@ -27,29 +28,12 @@ export const THINKING_LEVELS = [
     'xhigh',
     'max',
 ];
-/**
- * The levels a generic-relay declaration may hold — the vocabulary the
- * settings surfaces offer and the one the data layer admits. `off` is the
- * sole exclusion: it is not an intensity tier but a *disable* wire
- * (`reasoning_effort: 'none'`), and no generic relay is presumed to honor
- * that encoding; built-in providers that support it get `off` from their own
- * metadata instead. `minimal` and every effort tier above are pure
- * intensity values — the user declaring them is the authority on what the
- * relay accepts.
- */
-export const DECLARABLE_RELAY_THINKING_LEVELS = THINKING_LEVELS.filter((level) => level !== 'off');
+/** Relay declarations contain effort tiers; switches require a provider-specific wire. */
+export const DECLARABLE_RELAY_THINKING_LEVELS = THINKING_LEVELS.filter((level) => level !== 'off' && level !== 'on');
 export function isThinkingLevel(value) {
     return typeof value === 'string' && THINKING_LEVELS.includes(value);
 }
-/**
- * Derive the user-facing thinking-level choices from a model's declared
- * `ThinkingOptions`. `none` (OpenAI's off effort) and declared `offBehavior`
- * surface as `'off'`; other effort values map to the same-named
- * `ThinkingLevel`. Raw `toggle` alone is intentionally not enough because some
- * adapters have no real disabled wire. Unknown effort values (not in
- * `ThinkingLevel`) are dropped. Returns `[]` for models with no declared
- * options (miss → no thinking menu, fallback default).
- */
+/** Only expose controls the adapter can encode; unknown effort values are ignored. */
 function deriveThinkingChoices(options) {
     if (!options)
         return [];
@@ -59,10 +43,13 @@ function deriveThinkingChoices(options) {
     for (const effort of options.efforts ?? []) {
         if (effort === 'none')
             choices.add('off');
-        else if (isThinkingLevel(effort))
+        else if (DECLARABLE_RELAY_THINKING_LEVELS.includes(effort)) {
             choices.add(effort);
-        // Unknown effort values (not in ThinkingLevel) are dropped — add the
-        // level to THINKING_LEVELS if a provider introduces a new effort tier.
+        }
+    }
+    // Legacy Claude models need an explicit enabled request and have no effort knob.
+    if (options.offBehavior === 'anthropic-thinking-disabled' && choices.size === 1) {
+        choices.add('on');
     }
     return THINKING_LEVELS.filter((level) => choices.has(level));
 }
@@ -108,12 +95,6 @@ function normalizeModelOverride(entry) {
         return undefined;
     const declared = {};
     if (Array.isArray(entry.thinkingLevels)) {
-        // Declared levels are filtered to the declarable vocabulary, not merely
-        // the level vocabulary: `off` is a disable-wire encoding no generic
-        // relay is presumed to speak, and a declaration table has no business
-        // carrying it. The codec rejects it in persisted documents for the same
-        // reason; normalize silently drops it because it also sanitizes input
-        // that never passed a validator (settings drafts, hand-edited tables).
         const declaredSet = new Set(entry.thinkingLevels.filter((level) => isThinkingLevel(level) &&
             DECLARABLE_RELAY_THINKING_LEVELS.includes(level)));
         if (declaredSet.size > 0) {

package/node_modules/@maka/core/dist/recall.js

@@ -635,7 +635,15 @@ function optionalTimestamp(value) {
         return null;
     return value;
 }
-function eligibleSessions(sessions, filter) {
+/** Complete read-only history corpus for plugin organizers; same privacy and
+ * revision rules as Recall, without the search query's scan-count cap. */
+export async function listRecallHistorySessions(deps, activeSessionId) {
+    const privacy = validateWorkspacePrivacyContext(await deps.getPrivacyContext());
+    if (!privacy.ok || privacy.value.incognitoActive)
+        throw new Error('History is unavailable while workspace privacy cannot be verified or incognito is active');
+    return eligibleSessions(collapseSessionRevisions(await deps.listSessions(), activeSessionId), { includeArchived: false }, Number.POSITIVE_INFINITY);
+}
+function eligibleSessions(sessions, filter, limit = MAX_SESSIONS_SCANNED) {
     return sessions
         .filter((session) => 
     // Retired simulator transcripts are task records, not real history;
@@ -647,7 +655,7 @@ function eligibleSessions(sessions, filter) {
         const byTime = (right.lastMessageAt ?? 0) - (left.lastMessageAt ?? 0);
         return byTime !== 0 ? byTime : left.id.localeCompare(right.id);
     })
-        .slice(0, MAX_SESSIONS_SCANNED);
+        .slice(0, limit);
 }
 async function readFacts(deps, terms, options) {
     if (!deps.searchFacts)

package/node_modules/@maka/core/dist/session.js

@@ -965,3 +965,5 @@ function inferLegacyTurnStatus(messages) {
         return 'failed';
     return 'completed';
 }
+/** Durable provenance for assistant-created workers; visibility is a client preference. */
+export const ASSISTANT_BACKGROUND_SESSION_LABEL = 'personal-assistant-background';

package/node_modules/@maka/core/dist/settings.js

@@ -340,6 +340,7 @@ export function createDefaultSettings() {
             activeTab: 'requests',
         },
         appearance: {
+            showAssistantBackgroundSessions: false,
             workbarTogglePosition: 'titlebar',
             theme: 'auto',
             palette: 'default',
@@ -517,6 +518,7 @@ export function normalizeSettings(input) {
         // position; UI density is no longer a product setting.
         appearance: {
             ...appearanceWithoutLegacyFields,
+            showAssistantBackgroundSessions: base.appearance.showAssistantBackgroundSessions === true,
             workbarTogglePosition: base.appearance.workbarTogglePosition === 'edge' ? 'edge' : 'titlebar',
             palette: isThemePalette(base.appearance.palette) ? base.appearance.palette : 'default',
             // Same fail-closed rule as `palette` above, for the same reason: an

package/node_modules/@maka/core/dist/subagent-settings.js

@@ -81,5 +81,6 @@ export function normalizeSubagentSettings(input) {
             enabled: value.enabled,
         });
     }
-    return { presets };
+    const enabled = input.enabled;
+    return { ...(typeof enabled === 'boolean' ? { enabled } : {}), presets };
 }

package/node_modules/@maka/core/package.json

@@ -63,6 +63,8 @@
     "./context-offload": "./dist/context-offload.js",
     "./tool-result-archive-evidence": "./dist/tool-result-archive-evidence.js",
     "./attachments": "./dist/attachments.js",
+    "./image-delivery": "./dist/image-delivery.js",
+    "./image-markdown": "./dist/image-markdown.js",
     "./artifacts": "./dist/artifacts.js",
     "./pet": "./dist/pet.js",
     "./skill-invocation": "./dist/skill-invocation.js",
@@ -169,6 +171,7 @@
     "./workhub-routing": "./dist/workhub-routing.js"
   },
   "dependencies": {
-    "intl-messageformat": "11.2.15"
+    "intl-messageformat": "11.2.15",
+    "marked": "18.0.11"
   }
 }

package/node_modules/@maka/runtime/dist/ai-sdk-turn.js

@@ -1121,6 +1121,7 @@ export class AiSdkTurn {
                 const requestProjection = shapedProjection;
                 const completedProviderSteps = [];
                 let requestMessages = messages;
+                let finishFeedback;
                 let result;
                 let providerOutcome;
                 let finishReason = 'stop';
@@ -1161,10 +1162,12 @@ export class AiSdkTurn {
                     }
                     const requestSystemPromptBase = joinPromptFragments([
                         systemPrompt,
+                        finishFeedback,
                         finalChildSummaryStep ? CHILD_STEP_BUDGET_FINALIZATION_PROMPT : undefined,
                         toolRuntime.hasSandboxBoundaryDenial() ? SANDBOX_BOUNDARY_DENIED_FOR_TURN : undefined,
                         sandboxBoundaryFinalizationStep ? SANDBOX_BOUNDARY_FINALIZATION_PROMPT : undefined,
                     ]);
+                    finishFeedback = undefined;
                     const codeModeCatalogPrompt = toolMode === 'code_mode'
                         ? renderCodeModeCatalogPrompt(toolRuntime.hasSandboxBoundaryDenial()
                             ? new Map([...nestedTools].filter(([name]) => name !== REQUEST_SANDBOX_BOUNDARY_TOOL_NAME))
@@ -1929,6 +1932,26 @@ export class AiSdkTurn {
                             continue agentLoop;
                         }
                     }
+                    if (mayTakeAnotherStep &&
+                        returnedToolCalls.length === 0 &&
+                        this.deps.backend.beforeTurnFinish &&
+                        this.deps.backend.loadTurnRuntimeEvents &&
+                        this.deps.modelAdapter.mapFinishReason(finishReason) === 'end_turn') {
+                        const decision = await this.deps.backend.beforeTurnFinish({
+                            sessionId: this.deps.backend.sessionId,
+                            turnId,
+                            signal: turnAbortController.signal,
+                        });
+                        if (!decision.allow && !this.aborted && !this.loopStopRequested) {
+                            if ((await input.handoffBoundary?.(turnAbortController.signal, maxSteps === undefined ? null : maxSteps - runtimeSteps)) === 'pause') {
+                                this.handoffPaused = true;
+                                break agentLoop;
+                            }
+                            finishFeedback = decision.feedback;
+                            currentStepMessageId = this.deps.newId();
+                            continue agentLoop;
+                        }
+                    }
                     break agentLoop;
                 }
                 // Refine Tool Availability against the final active set. Deferred

package/node_modules/@maka/runtime/dist/filesystem-executor.js

@@ -270,6 +270,8 @@ function createWorkspaceFilesystemExecutor(workspace) {
                     const result = await workspace.readFile({
                         cwd,
                         path,
+                        ...(operation.imagePurpose ? { imagePurpose: operation.imagePurpose } : {}),
+                        ...(abortSignal ? { abortSignal } : {}),
                     });
                     if ('bytes' in result) {
                         return { kind: 'read_image', bytes: result.bytes, mimeType: result.mimeType };

package/node_modules/@maka/runtime/dist/filesystem-worker/operations.js

@@ -30,7 +30,7 @@ import { readPage } from '../read-page.js';
 import { formatJsonText } from '../format-json.js';
 import { createEditUnifiedDiff, createUnifiedDiff } from '../unified-diff.js';
 import { compareAndDeleteEntry, hostVisibilityAfterWrite, openStableTarget, readModifyWriteThroughHandle, StableWriteFailure, writeThroughHandle, } from '../file-stable-write.js';
-import { readWorkspaceFile } from '../image-file.js';
+import { ImageFileError, readWorkspaceFile } from '../image-file.js';
 import { FILESYSTEM_WORKER_PROTOCOL_VERSION, operationAccess, operationUsesDirectoryEntry, } from './protocol.js';
 import { isLikelySandboxDenial } from '../sandbox/detect.js';
 // Canonicalisation must match the sandbox the worker runs in: realpath-based
@@ -61,8 +61,10 @@ export async function executeFilesystemOperation(operation, operationBoundary, d
     switch (operation.kind) {
         case 'read': {
             const path = await resolveExistingAllowed(operation.cwd, operation.path, 'Read', 'read', operationBoundary);
-            const file = await readWorkspaceFile(path).catch((error) => {
-                throw operationError('filesystem_error', error instanceof Error ? error.message : 'File could not be read.');
+            const file = await readWorkspaceFile(path, {
+                ...(operation.imagePurpose ? { imagePurpose: operation.imagePurpose } : {}),
+            }).catch((error) => {
+                throw operationError(normalizeOperationError(error).code, error instanceof Error ? error.message : 'File could not be read.');
             });
             if ('bytes' in file) {
                 return {
@@ -318,6 +320,8 @@ function operationError(code, message) {
 function normalizeOperationError(error) {
     if (error instanceof FilesystemOperationError)
         return error;
+    if (error instanceof ImageFileError)
+        return operationError(error.code === 'ERR_IMAGE_TOO_LARGE' ? 'image_too_large' : 'invalid_image', error.message);
     if (error instanceof StableWriteFailure) {
         return operationError(error.code, error.message);
     }

package/node_modules/@maka/runtime/dist/filesystem-worker/protocol.js

@@ -20,10 +20,9 @@ import { z } from 'zod';
 import { readContinuationSchema, readPageSchema } from '../read-page.js';
 import { validateSandboxBoundaryExpansion } from '@maka/core/sandbox-boundary';
 import { GREP_MAX_LINES, GREP_MAX_LINES_PER_FILE, GREP_MAX_MATCH_BYTES } from '../grep-search.js';
-// v10 adds bounded Read pages to v9's exact Grep counts; v11 adds Glob's
-// truncation flag to v10's result contract. Older workers cannot satisfy the
-// combined result contract and must be rejected at the handshake.
-export const FILESYSTEM_WORKER_PROTOCOL_VERSION = 11;
+// v12 adds chat image reads with a bounded payload and no model dimension limit.
+// Older workers cannot satisfy this read policy and must be rejected at the handshake.
+export const FILESYSTEM_WORKER_PROTOCOL_VERSION = 12;
 /** The single authority on which operation kinds are writes. Shared by the
  * client (permission/identity decisions) and the worker (operation guards) so
  * the set cannot drift. */
@@ -98,6 +97,7 @@ export const FilesystemWorkerOperationSchema = z.union([
         kind: z.literal('read'),
         cwd,
         path,
+        imagePurpose: z.literal('chat').optional(),
         offset: z.number().int().nonnegative().optional(),
         limit: z.number().int().positive().optional(),
         continuation: readContinuationSchema.optional(),
@@ -236,6 +236,8 @@ export const FilesystemWorkerErrorCodeSchema = z.enum([
     'grep_unavailable',
     'sandbox_denied',
     'filesystem_denied',
+    'image_too_large',
+    'invalid_image',
     'filesystem_error',
     // The worker may have applied the mutation before it lost the ability to
     // report back (e.g. it wrote the file then the post-write identity check

package/node_modules/@maka/runtime/dist/image-file-reader.js

@@ -0,0 +1,83 @@
+/*
+ * 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 { createBoundaryFilesystemExecutor, } from './filesystem-executor.js';
+import { createLocalWorkspaceExecutor } from './workspace-executor.js';
+import { ImageFileError, imageFileFailureReason } from './image-file.js';
+import { FilesystemWorkerClientError } from './filesystem-worker/client.js';
+import { SandboxCommandError } from './sandbox/errors.js';
+/** Normalizes filesystem backends at the image reader boundary. */
+export class ImageFileReadError extends Error {
+    reason;
+    constructor(reason, cause) {
+        super(cause instanceof Error ? cause.message : `Image read failed: ${reason}`, { cause });
+        this.reason = reason;
+        this.name = 'ImageFileReadError';
+    }
+}
+function readFailure(error) {
+    if (error instanceof ImageFileError)
+        return imageFileFailureReason(error);
+    if (error instanceof SandboxCommandError)
+        return 'not_allowed';
+    const code = error instanceof FilesystemWorkerClientError
+        ? error.reason
+        : error?.code;
+    switch (code) {
+        case 'image_too_large':
+            return 'too_large';
+        case 'invalid_image':
+            return 'unsupported_mime';
+        case 'ENOENT':
+        case 'ENOTDIR':
+        case 'not_found':
+            return 'not_found';
+        case 'EACCES':
+        case 'EPERM':
+        case 'filesystem_denied':
+        case 'path_denied':
+        case 'sandbox_denied':
+        case 'sandbox_required':
+        case 'sandbox_boundary_required':
+            return 'not_allowed';
+        default:
+            return 'read_failed';
+    }
+}
+/** The same filesystem boundary as Read, without model snapshots or tool execution. */
+export function createImageFileReader(options = {}) {
+    const filesystem = createBoundaryFilesystemExecutor({
+        workspace: options.executor ?? createLocalWorkspaceExecutor(),
+        ...(options.filesystemWorker ? { worker: options.filesystemWorker } : {}),
+        ...(options.permissionProfile ? { permissionProfile: options.permissionProfile } : {}),
+    });
+    return async (input) => {
+        const { path, ...context } = input;
+        const result = await filesystem
+            .execute({
+            ...context,
+            operation: { kind: 'read', path, imagePurpose: 'chat' },
+        })
+            .catch((error) => {
+            throw new ImageFileReadError(readFailure(error), error);
+        });
+        if (result.kind !== 'read_image')
+            throw new ImageFileReadError('unsupported_mime');
+        return { bytes: result.bytes, mimeType: result.mimeType };
+    };
+}