maka-agent 0.2.0-dev.41.20260918 → 0.2.0-dev.42.20260918

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

@@ -52,6 +52,9 @@
  * plus one weight that BM25 has no way to express: a tool result's term
  * density reflects machine output rather than relevance.
  */
+import { isCanonicalArtifactEntityId } from './artifacts.js';
+import { formatAttachmentResourceRef, MAX_ATTACHMENT_COUNT } from './attachments.js';
+import { isAttachmentRef } from './events.js';
 import { validateWorkspacePrivacyContext } from './incognito.js';
 import { redactSecrets } from './redaction.js';
 import { SEARCH_QUERY_MAX_CHARS } from './search.js';
@@ -180,6 +183,76 @@ function stripSyntheticText(text, patterns) {
         stripped = stripped.replace(pattern, '');
     return stripped;
 }
+/**
+ * The files a message carried. A screenshot pasted under "have a look" leaves
+ * no trace in the text, so without this the message is unreachable by any
+ * term the user would think to search.
+ */
+export function recallMaterials(message) {
+    if (message.type !== 'user')
+        return [];
+    const attachments = message.attachments;
+    if (!Array.isArray(attachments) || attachments.length === 0)
+        return [];
+    // Shape first, then the cap: a record older or stranger than the current
+    // shape projects nothing, and a run of those ahead of a valid attachment
+    // must not spend the cap that valid one needed.
+    return attachments
+        .filter(isAttachmentRef)
+        .slice(0, MAX_ATTACHMENT_COUNT)
+        .map((attachment) => {
+        const resource = readableAttachmentResource(attachment);
+        const location = retrievableMaterialLocation(attachment);
+        return {
+            name: attachment.name,
+            kind: attachment.kind,
+            mimeType: attachment.mimeType,
+            bytes: attachment.bytes,
+            ...(resource ? { resource } : {}),
+            ...(location ?? {}),
+        };
+    });
+}
+/**
+ * The address `Read` accepts, present only for a material `Read` can actually
+ * return. `Read` answers an image with the image and anything else with the
+ * file's text, and refuses a PDF outright — so a PDF's address is one the
+ * caller can only fail on, which is the same reason a material in another
+ * Session carries no address.
+ */
+function readableAttachmentResource(attachment) {
+    if (attachment.kind === 'pdf')
+        return null;
+    return formatAttachmentResourceRef(attachment.ref);
+}
+/**
+ * The pair that names a material a retrieval tool can fetch: the Session that
+ * holds it and the artifact inside it. Only a durable Session artifact can be
+ * fetched, so a ref of any other kind names nothing.
+ */
+function retrievableMaterialLocation(attachment) {
+    if (attachment.ref.kind !== 'session_file')
+        return null;
+    if (!isCanonicalArtifactEntityId(attachment.ref.relativePath))
+        return null;
+    return {
+        sourceSessionId: attachment.ref.sessionId,
+        materialId: attachment.ref.relativePath,
+    };
+}
+/**
+ * What the predicate runs on: a message's prose plus the names of the files it
+ * carried, so a material is reachable by the name a person would remember.
+ * Names are matched but not returned as text — they come back as materials.
+ */
+function recallMatchableText(message) {
+    const prose = recallSearchableText(message);
+    const materials = recallMaterials(message);
+    if (materials.length === 0)
+        return prose;
+    const names = materials.map((material) => material.name).join('\n');
+    return prose === undefined || prose.length === 0 ? names : `${prose}\n${names}`;
+}
 /** Visits every string value in a JSON-like value, in document order, until the visitor declines. */
 function collectStringLeaves(value, visit) {
     if (typeof value === 'string')
@@ -261,7 +334,7 @@ export async function runRecall(request, deps, options = {}) {
     collected.hits.sort((left, right) => right.score - left.score || compareHitOrder(left, right));
     const sessionById = new Map(sessions.map((session) => [session.id, session]));
     const anchors = applySessionQuota(collected.hits, limit);
-    const passages = assemblePassages(collected.transcripts, anchors, sessionById);
+    const passages = assemblePassages(collected.transcripts, anchors, sessionById, options.activeSessionId);
     return {
         ok: true,
         facts,
@@ -334,7 +407,7 @@ export async function expandRecallPassage(request, deps, options = {}) {
     if (!transcript) {
         return { ok: false, reason: 'not_found', message: 'That Session was not found.' };
     }
-    const message = transcript.find((candidate) => candidate.id === anchorMessageId && recallSearchableText(candidate) !== undefined);
+    const message = transcript.find((candidate) => candidate.id === anchorMessageId && isPassageMessage(candidate));
     if (!message) {
         return { ok: false, reason: 'not_found', message: 'That passage anchor was not found.' };
     }
@@ -355,12 +428,77 @@ export async function expandRecallPassage(request, deps, options = {}) {
         tf: new Map(),
         matchedTerms: [],
         score: 0,
-    }, transcript, session, RECALL_PASSAGE_MAX_BYTES, { before, after });
+    }, transcript, session, RECALL_PASSAGE_MAX_BYTES, options.activeSessionId, { before, after });
     if (!built) {
         return { ok: false, reason: 'not_found', message: 'That passage could not be rebuilt.' };
     }
     return { ok: true, passage: built.passage };
 }
+/**
+ * Brings one material named by a passage into the asking Session.
+ *
+ * The Session check is the point of this function, not a formality: without it
+ * the tool would be a way to read any artifact by id, including from the
+ * Sessions recall itself refuses to surface — incognito, retired simulator
+ * transcripts, whatever a future rule excludes. A material is retrievable
+ * exactly when recall could have shown you the Session it sits in.
+ */
+export async function fetchRecallMaterial(request, deps, options = {}) {
+    if (options.abortSignal?.aborted)
+        return aborted();
+    if (!deps.fetchMaterial) {
+        return { ok: false, reason: 'not_found', message: 'Materials are unavailable here.' };
+    }
+    if (typeof request !== 'object' || request === null || Array.isArray(request)) {
+        return { ok: false, reason: 'invalid_query', message: 'Material request must be an object.' };
+    }
+    const record = request;
+    const sessionId = optionalString(record.sessionId);
+    const materialId = optionalString(record.materialId);
+    if (!sessionId || !materialId) {
+        return {
+            ok: false,
+            reason: 'invalid_query',
+            message: 'A material is named by its Session and its material id.',
+        };
+    }
+    if (!options.activeSessionId) {
+        return { ok: false, reason: 'not_found', message: 'Materials need an active Session.' };
+    }
+    const privacyPayload = await deps.getPrivacyContext();
+    if (options.abortSignal?.aborted)
+        return aborted();
+    const privacy = validateWorkspacePrivacyContext(privacyPayload);
+    if (!privacy.ok || privacy.value.incognitoActive) {
+        return {
+            ok: false,
+            reason: 'incognito_active',
+            message: 'Recall is unavailable while incognito is active.',
+        };
+    }
+    const sessions = eligibleSessions(collapseSessionRevisions(await deps.listSessions(), options.activeSessionId), { sessionId, includeArchived: options.includeArchived === true });
+    if (options.abortSignal?.aborted)
+        return aborted();
+    if (!sessions.some((candidate) => candidate.id === sessionId)) {
+        return { ok: false, reason: 'not_found', message: 'That material was not found.' };
+    }
+    const fetched = await deps.fetchMaterial({
+        sourceSessionId: sessionId,
+        materialId,
+        targetSessionId: options.activeSessionId,
+        ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+    });
+    if (options.abortSignal?.aborted)
+        return aborted();
+    if (!fetched.ok) {
+        return {
+            ok: false,
+            reason: fetched.reason === 'unsupported' ? 'invalid_query' : 'not_found',
+            message: fetched.message,
+        };
+    }
+    return { ok: true, content: fetched.content };
+}
 function normalizeSpan(value) {
     if (value === undefined)
         return RECALL_EXPAND_MAX_NEIGHBOURS;
@@ -602,7 +740,7 @@ function verify(sessionId, message, input) {
     if (sessionId === input.activeSessionId && turnId && input.excludeTurnIds?.has(turnId)) {
         return undefined;
     }
-    const raw = recallSearchableText(message);
+    const raw = recallMatchableText(message);
     if (raw === undefined)
         return undefined;
     // A hit is a term that occurs in the text as it was stored *and* still
@@ -738,7 +876,7 @@ function applySessionQuota(hits, limit) {
     // first when the total cap binds.
     return selected.sort((left, right) => right.score - left.score);
 }
-function assemblePassages(transcripts, anchors, sessionById) {
+function assemblePassages(transcripts, anchors, sessionById, activeSessionId) {
     if (anchors.length === 0)
         return [];
     const passages = [];
@@ -749,7 +887,7 @@ function assemblePassages(transcripts, anchors, sessionById) {
         const transcript = transcripts.get(anchor.sessionId);
         if (!transcript)
             continue;
-        const built = buildPassage(anchor, transcript, sessionById.get(anchor.sessionId), remaining);
+        const built = buildPassage(anchor, transcript, sessionById.get(anchor.sessionId), remaining, activeSessionId);
         if (!built)
             continue;
         remaining -= built.bytes;
@@ -757,7 +895,7 @@ function assemblePassages(transcripts, anchors, sessionById) {
     }
     return passages;
 }
-function buildPassage(anchor, transcript, session, budget, span = {
+function buildPassage(anchor, transcript, session, budget, activeSessionId, span = {
     before: RECALL_PASSAGE_NEIGHBOURS,
     after: RECALL_PASSAGE_NEIGHBOURS,
 }) {
@@ -779,7 +917,7 @@ function buildPassage(anchor, transcript, session, budget, span = {
     const render = (message, isAnchor) => {
         if (rendered.has(message.id))
             return;
-        const projected = projectPassageMessage(message, isAnchor);
+        const projected = projectPassageMessage(message, isAnchor, activeSessionId);
         if (!projected)
             return;
         const overhead = Buffer.byteLength(JSON.stringify({ ...projected, text: '' }), 'utf8');
@@ -816,8 +954,7 @@ function buildPassage(anchor, transcript, session, budget, span = {
     // the caller can still reach, so it counts toward the continuation flags the
     // same way one beyond the span does. Reporting otherwise would tell a caller
     // there is nothing more in a direction recall just cut short.
-    const omitted = (entries) => entries.some((entry) => !rendered.has(entry.message.id) &&
-        projectPassageMessage(entry.message, false) !== undefined);
+    const omitted = (entries) => entries.some((entry) => !rendered.has(entry.message.id) && isPassageMessage(entry.message));
     const passage = {
         sessionId: anchor.sessionId,
         sessionTitle: redactSecrets(session?.name ?? ''),
@@ -877,13 +1014,36 @@ function collectNeighbours(transcript, anchorIndex, turnId, span) {
 function isPassageNeighbour(message) {
     return message.type === 'user' || message.type === 'assistant' || message.type === 'tool_call';
 }
-function projectPassageMessage(message, isAnchor) {
+/**
+ * Whether a message can appear in a passage at all. Redaction rewrites text
+ * but never empties it, so this decides the same set `projectPassageMessage`
+ * does without paying for redaction on every message a lookup walks past.
+ */
+function isPassageMessage(message) {
     const raw = recallSearchableText(message);
-    if (raw === undefined)
-        return undefined;
-    const text = redactSecrets(raw).trim();
-    if (text.length === 0)
+    if (raw !== undefined && raw.trim().length > 0)
+        return true;
+    return recallMaterials(message).length > 0;
+}
+function projectPassageMessage(message, isAnchor, activeSessionId) {
+    const raw = recallSearchableText(message);
+    const text = raw === undefined ? '' : redactSecrets(raw).trim();
+    // A message whose whole content was a pasted file has no text of its own.
+    // Dropping it would make the file unreachable in exactly the case this
+    // layer exists for.
+    // A file name is user-authored text like any other, so it leaves through the
+    // same redaction the passage body does; the address beside it is a runtime
+    // identifier and carries nothing to redact.
+    const materials = recallMaterials(message).map((material) => ({
+        ...material,
+        name: redactSecrets(material.name),
+    }));
+    if (text.length === 0 && materials.length === 0)
         return undefined;
+    // A material carries an address or a location, never both: the address says
+    // "read this now", the location says "ask for it and it will be brought
+    // here". Offering an address `Read` would refuse is the mistake this split
+    // exists to prevent.
     return {
         messageId: message.id,
         role: passageRole(message),
@@ -891,6 +1051,29 @@ function projectPassageMessage(message, isAnchor) {
         text,
         timestamp: message.ts,
         isAnchor,
+        ...(materials.length > 0
+            ? { materials: materials.map((material) => addressOrLocation(material, activeSessionId)) }
+            : {}),
+    };
+}
+/**
+ * Reachability is a fact about where the material itself is stored, not about
+ * the passage that mentioned it. Keying it on the passage would offer an
+ * address for a ref pointing into another Session — the doomed address this
+ * split exists to prevent, with the polarity inverted.
+ */
+function addressOrLocation(material, activeSessionId) {
+    const { resource, sourceSessionId, materialId, ...named } = material;
+    if (resource && sourceSessionId !== undefined && sourceSessionId === activeSessionId) {
+        return { ...named, resource };
+    }
+    // A location is a thing to ask for, so it is only worth carrying when
+    // asking could succeed. A PDF is refused wherever it is stored.
+    return {
+        ...named,
+        ...(sourceSessionId && materialId && named.kind !== 'pdf'
+            ? { sourceSessionId, materialId }
+            : {}),
     };
 }
 function passageRole(message) {

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

@@ -197,6 +197,14 @@ export function classifyGeneralizedError(error) {
         return 'timeout';
     if (lower.includes('429') || lower.includes('rate'))
         return 'rate_limited';
+    // builder-util-runtime appends generic authentication-token advice to HTTP
+    // 404 errors. electron-updater has already classified this particular case
+    // as a missing channel artifact, so it is not evidence of bad credentials.
+    if (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ERR_UPDATER_CHANNEL_FILE_NOT_FOUND')
+        return undefined;
     if (lower.includes('401') || lower.includes('403') || isAuthenticationErrorText(lower))
         return 'auth_failed';
     if (/\b5\d\d\b/.test(lower))

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

@@ -0,0 +1,149 @@
+/*
+ * 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 { redactSecrets } from './redaction.js';
+import { userFacingText } from './session.js';
+const utf8Encoder = new TextEncoder();
+/** Default per-reference budget. It is deliberately small enough to leave room for the active task. */
+export const SESSION_SNAPSHOT_DEFAULT_MAX_CHARS = 12_000;
+export const SESSION_SNAPSHOT_MAX_CHARS = 32_000;
+export const SESSION_SNAPSHOT_MAX_BYTES = 32_000;
+export const SESSION_SNAPSHOT_MAX_ITEMS = 24;
+/**
+ * Build the model-safe portion of a Session transcript.
+ *
+ * Only user and assistant text is shareable. Tool calls/results, permission
+ * events, system notes, and other Runtime records remain outside this
+ * projection. Items are selected from the tail, then restored to transcript
+ * order so a large history cannot crowd the current request unexpectedly.
+ */
+export function createSessionSnapshot(messages, options) {
+    const maxChars = clampPositiveInteger(options.maxChars ?? SESSION_SNAPSHOT_DEFAULT_MAX_CHARS, 1, SESSION_SNAPSHOT_MAX_CHARS);
+    const maxItems = clampPositiveInteger(options.maxItems ?? SESSION_SNAPSHOT_MAX_ITEMS, 1, SESSION_SNAPSHOT_MAX_ITEMS);
+    const candidates = messages.flatMap((message) => {
+        if (message.type !== 'user' && message.type !== 'assistant')
+            return [];
+        const text = message.type === 'user' ? userFacingText(message) : message.text;
+        const normalized = redactSecrets(text).trim();
+        if (!normalized)
+            return [];
+        return [
+            {
+                role: message.type,
+                text: normalized,
+                turnId: message.turnId,
+                ts: message.ts,
+            },
+        ];
+    });
+    const selected = [];
+    let usedChars = 0;
+    let usedBytes = 0;
+    let truncated = false;
+    for (let index = candidates.length - 1; index >= 0 && selected.length < maxItems; index -= 1) {
+        const candidate = candidates[index];
+        const line = formatSnapshotItem(candidate);
+        const separator = selected.length > 0 ? 2 : 0;
+        const available = maxChars - usedChars - separator;
+        const availableBytes = SESSION_SNAPSHOT_MAX_BYTES - usedBytes - separator;
+        if (available <= 0 || availableBytes <= 0) {
+            truncated = true;
+            break;
+        }
+        const lineBytes = utf8Encoder.encode(line).byteLength;
+        if (line.length <= available && lineBytes <= availableBytes) {
+            selected.push(candidate);
+            usedChars += separator + line.length;
+            usedBytes += separator + lineBytes;
+            continue;
+        }
+        if (selected.length === 0) {
+            const prefix = formatSnapshotItem({ ...candidate, text: '' });
+            const contentBudget = Math.max(0, available - prefix.length);
+            const byteBudget = Math.max(0, availableBytes - utf8Encoder.encode(prefix).byteLength);
+            if (contentBudget > 0 && byteBudget > 0) {
+                const text = sliceAtUtf8Boundary(sliceAtCodePointBoundary(candidate.text, contentBudget), byteBudget).trimEnd();
+                if (!text) {
+                    truncated = true;
+                    break;
+                }
+                selected.push({
+                    ...candidate,
+                    text,
+                });
+                usedChars = maxChars;
+            }
+        }
+        truncated = true;
+        break;
+    }
+    if (selected.length < candidates.length)
+        truncated = true;
+    selected.reverse();
+    const text = sliceAtCodePointBoundary(selected.map(formatSnapshotItem).join('\n\n'), maxChars);
+    return {
+        reference: {
+            sessionId: options.sessionId,
+            sessionName: redactSecrets(options.sessionName),
+            capturedAt: options.capturedAt ?? Date.now(),
+        },
+        items: selected,
+        text,
+        estimatedTokens: Math.ceil(text.length / 4),
+        maxChars,
+        truncated,
+    };
+}
+/** Convert a snapshot into the existing inline quote transport. */
+export function sessionSnapshotToQuote(snapshot) {
+    const sessionName = redactSecrets(snapshot.reference.sessionName);
+    return {
+        text: snapshot.text,
+        label: sliceAtCodePointBoundary(`Session: ${sessionName}`, 200),
+        sourceSessionId: snapshot.reference.sessionId,
+        sourceSessionName: sliceAtCodePointBoundary(sessionName, 200),
+        sourceCapturedAt: snapshot.reference.capturedAt,
+        sourceTruncated: snapshot.truncated,
+    };
+}
+function formatSnapshotItem(item) {
+    return `${item.role === 'user' ? 'User' : 'Assistant'}: ${item.text}`;
+}
+/** Keep a UTF-16 slice from ending between the halves of a surrogate pair. */
+function sliceAtCodePointBoundary(value, maxCodeUnits) {
+    const sliced = value.slice(0, maxCodeUnits);
+    const last = sliced.charCodeAt(sliced.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? sliced.slice(0, -1) : sliced;
+}
+function sliceAtUtf8Boundary(value, maxBytes) {
+    let bytes = 0;
+    let end = 0;
+    for (const codePoint of value) {
+        const nextBytes = utf8Encoder.encode(codePoint).byteLength;
+        if (bytes + nextBytes > maxBytes)
+            break;
+        bytes += nextBytes;
+        end += codePoint.length;
+    }
+    return value.slice(0, end);
+}
+function clampPositiveInteger(value, min, max) {
+    if (!Number.isSafeInteger(value))
+        return min;
+    return Math.max(min, Math.min(max, value));
+}

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

@@ -29,6 +29,7 @@
     "./provider-retry-countdown": "./dist/provider-retry-countdown.js",
     "./interaction": "./dist/interaction.js",
     "./session": "./dist/session.js",
+    "./session-reference": "./dist/session-reference.js",
     "./session-revisions": "./dist/session-revisions.js",
     "./collaboration": "./dist/collaboration.js",
     "./orchestration": "./dist/orchestration.js",
@@ -66,6 +67,7 @@
     "./capabilities": "./dist/capabilities.js",
     "./capability-audit": "./dist/capability-audit.js",
     "./client-capability-grant": "./dist/client-capability-grant.js",
+    "./client-plugin-bridge": "./dist/client-plugin-bridge.js",
     "./health": "./dist/health.js",
     "./search": "./dist/search.js",
     "./bot-events": "./dist/bot-events.js",

package/node_modules/@maka/runtime/dist/model-factory.js

@@ -654,11 +654,13 @@ function buildFamilyWire(connection, modelId, level, thinkingOptions, requestedL
                     : {},
             };
         case 'commandcode-cli':
-            // The CLI wire takes `reasoning_effort` as the CLI's own effort words;
-            // `max` has no counterpart there and rounds down to `high`.
+            // The CLI wire takes `reasoning_effort` as the CLI's own effort words.
+            // `max` is one of them (claude-fable-5-1, moonshotai/Kimi-K3, …), so the
+            // chosen level is forwarded verbatim — rounding it down would silently
+            // send a weaker request than the user asked for.
             return level === undefined || level === 'off'
                 ? {}
-                : { 'commandcode-cli': { reasoningEffort: level === 'max' ? 'high' : level } };
+                : { 'commandcode-cli': { reasoningEffort: level } };
         default:
             return {};
     }

package/node_modules/@maka/runtime/dist/model-history.js

@@ -799,8 +799,19 @@ function formatAttachmentRefs(attachments) {
 function formatQuoteRefs(quotes) {
     return quotes
         .map((q) => {
-        const label = q.label === undefined ? '' : ` label="${q.label.replace(/"/g, "'")}"`;
-        return `<quoted_excerpt${label}>\n${q.text}\n</quoted_excerpt>`;
+        const attributes = [
+            q.label === undefined ? undefined : `label="${quoteAttribute(q.label)}"`,
+            q.sourceSessionId === undefined
+                ? undefined
+                : `source_session="${quoteAttribute(q.sourceSessionId)}"`,
+            q.sourceCapturedAt === undefined ? undefined : `captured_at="${q.sourceCapturedAt}"`,
+            q.sourceTruncated === undefined ? undefined : `truncated="${q.sourceTruncated}"`,
+        ].filter((attribute) => attribute !== undefined);
+        const opening = attributes.length > 0 ? `<quoted_excerpt ${attributes.join(' ')}>` : '<quoted_excerpt>';
+        return `${opening}\n${q.text}\n</quoted_excerpt>`;
     })
         .join('\n');
 }
+function quoteAttribute(value) {
+    return value.replace(/["<&>]/g, (character) => character === '"' ? "'" : `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}