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

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

@@ -1386,17 +1386,12 @@ class RuntimeHostMakaSessionDriverImpl {
     async #stopUserCommand(ref, owner) {
         if (this.#activeUserCommands.get(ref) !== owner)
             return;
-        const stopped = await this.#request('runtime.resource.stop', {
+        await this.#request('runtime.resource.stop', {
             sessionId: owner.sessionId,
             ref,
         });
-        this.#publishShellRunUpdate({
-            sessionId: owner.sessionId,
-            ownership: { kind: 'local' },
-            sourceTurnId: owner.commandId,
-            sourceToolCallId: owner.commandId,
-            result: stopped.resource,
-        });
+        this.#activeUserCommands.delete(ref);
+        this.#publishRuntimeResource(owner.sessionId, ref);
     }
     #publishShellRunUpdate(update) {
         const owner = this.#activeUserCommands.get(update.result.ref);

package/node_modules/@maka/core/dist/shell-run.js

@@ -75,6 +75,17 @@ export function isTerminalShellRunStatus(value) {
 export function isActiveShellRunStatus(value) {
     return SHELL_RUN_ACTIVE_STATUSES.includes(value);
 }
+/** Desktop interactive-terminal launch identity, persisted as the run's source ids. */
+export const DESKTOP_TERMINAL_LAUNCH_PREFIX = 'desktop-terminal-';
+/**
+ * A Desktop-owned interactive terminal carries no transcript tool call, so
+ * nothing consumes the output on its update and wire projections.
+ */
+export function isDesktopTerminalShellRun(source) {
+    return (source.mode === 'pty' &&
+        source.sourceTurnId === source.sourceToolCallId &&
+        source.sourceTurnId.startsWith(DESKTOP_TERMINAL_LAUNCH_PREFIX));
+}
 export function isValidShellRunStatusTransition(current, next) {
     if (current === next)
         return true;

package/node_modules/@maka/runtime/dist/pty-screen-collector.js

@@ -66,6 +66,9 @@ export class PtyScreenCollector {
         this.installProtocolBoundary();
         this.lastGood = blankPtyOutput(cols, rows);
     }
+    get available() {
+        return !this.failure && !this.disposed;
+    }
     accept(data) {
         if (!data)
             return;
@@ -75,23 +78,46 @@ export class PtyScreenCollector {
         }
         const generation = ++this.admittedGeneration;
         const bytes = Buffer.byteLength(data, 'utf8');
-        const entry = { data, bytes, dropped: false };
+        // node-pty delivers many tiny events per tick; each queued parse is paced
+        // by the headless terminal's write scheduler, so queue depth — not byte
+        // volume — is what stalls cut-bound operations. Merge unstarted data into
+        // the tail entry: byte order is preserved and protocol replies already
+        // batch per write call.
+        const tail = this.pending.at(-1);
+        if (tail &&
+            !tail.dropped &&
+            !tail.started &&
+            tail.bytes + bytes <= PTY_PARSER_HIGH_WATER_BYTES) {
+            tail.data += data;
+            tail.bytes += bytes;
+            tail.generation = generation;
+        }
+        else {
+            this.enqueue({ data, bytes, generation, dropped: false, started: false });
+        }
         this.pendingBytes += bytes;
-        this.pending.push(entry);
         this.evictOldestIfOverBudget();
         this.options.onDirty(generation);
-        const parse = this.sequence.then(() => (entry.dropped ? undefined : this.write(entry.data)));
+    }
+    enqueue(entry) {
+        this.pending.push(entry);
+        const parse = this.sequence.then(() => {
+            if (entry.dropped)
+                return undefined;
+            entry.started = true;
+            return this.write(entry.data);
+        });
         this.sequence = parse.then(() => {
             if (entry.dropped)
                 return;
-            this.parsedGeneration = generation;
-            this.pendingBytes -= bytes;
+            this.parsedGeneration = entry.generation;
+            this.pendingBytes -= entry.bytes;
             const index = this.pending.indexOf(entry);
             if (index >= 0)
                 this.pending.splice(index, 1);
         }, (error) => {
             if (!entry.dropped)
-                this.pendingBytes -= bytes;
+                this.pendingBytes -= entry.bytes;
             this.fail(asError(error, 'PTY parser failed'));
         });
     }

package/node_modules/@maka/runtime/dist/shell-run-manager.js

@@ -241,7 +241,7 @@ export class ShellRunProcessManager {
         let resizeChanged = false;
         let operationFailed = false;
         let exitBeforeControlCut = false;
-        const controlCut = live.collector.mutateAndSnapshotAtCut(() => {
+        const mutation = () => {
             if (input.abortSignal?.aborted) {
                 throw abortError('WriteStdin aborted before the control operation was committed');
             }
@@ -287,8 +287,18 @@ export class ShellRunProcessManager {
                     this.handleIntegrityFailure(live, asError(error, 'PTY input write failed'));
                 }
             }
-        });
-        const persistedControl = this.persistObservation(live, controlCut.then((snapshot) => (operationFailed || exitBeforeControlCut ? undefined : snapshot), () => undefined));
+        };
+        // Client control replies carry no output, so the keystroke path only needs
+        // the ordered mutation, not the snapshot + persist. The record still
+        // refreshes through output-driven flushes; a resize changes the screen
+        // without output, so that one is persisted eagerly.
+        const clientControl = input.caller === 'client';
+        const controlCut = clientControl
+            ? live.collector.mutateAtCut(mutation).then(() => undefined)
+            : live.collector.mutateAndSnapshotAtCut(mutation);
+        const persistedControl = clientControl
+            ? undefined
+            : this.persistObservation(live, controlCut.then((snapshot) => (operationFailed || exitBeforeControlCut ? undefined : snapshot), () => undefined));
         try {
             await controlCut;
         }
@@ -312,20 +322,27 @@ export class ShellRunProcessManager {
             return shellRunContent(record, operation);
         }
         let record;
-        try {
-            record = await persistedControl;
-        }
-        catch (error) {
-            if (live.integrityFailure && !live.persistFailure) {
-                record = await this.markObserved(await live.finished.join());
-                return shellRunContent(record, ptyControlOperation(input, {
-                    inputQueued,
-                    resizeApplied,
-                    resizeChanged,
-                    failed: true,
-                }));
+        if (persistedControl) {
+            try {
+                record = await persistedControl;
             }
-            throw error;
+            catch (error) {
+                if (live.integrityFailure && !live.persistFailure) {
+                    record = await this.markObserved(await live.finished.join());
+                    return shellRunContent(record, ptyControlOperation(input, {
+                        inputQueued,
+                        resizeApplied,
+                        resizeChanged,
+                        failed: true,
+                    }));
+                }
+                throw error;
+            }
+        }
+        else {
+            record = live.record;
+            if (resizeChanged)
+                void this.persistObservation(live).catch(() => undefined);
         }
         if (live.integrityFailure && !live.persistFailure) {
             record = await this.markObserved(await live.finished.join());
@@ -336,7 +353,6 @@ export class ShellRunProcessManager {
                 failed: true,
             }));
         }
-        // persistObservation decides whether to join finalization at call time.
         // A real PTY can exit while that persist is still in flight, leaving a
         // running snapshot here even though finalizeOnce has already started.
         if (live.driverExit || live.finalizeOnce) {
@@ -345,7 +361,7 @@ export class ShellRunProcessManager {
         }
         if (isTerminalShellRunStatus(record.status))
             record = await this.markObserved(record);
-        return shellRunContent(record, operation);
+        return clientControl ? compactShellRunContent(record) : shellRunContent(record, operation);
     }
     async readRuntimeResource(sessionId, ref, abortSignal) {
         return this.resourceDetail(sessionId, ref, true, abortSignal, true);
@@ -428,11 +444,21 @@ export class ShellRunProcessManager {
         const live = this.live.get(target.shellRunId);
         if (!live || live.sessionId !== sessionId || live.mode !== 'pty')
             return null;
+        // The collector dies before the process exit lands: an integrity failure or
+        // startup cleanup leaves it throwing while `live` still looks attachable.
+        // Report the resource as gone so the caller repairs the stale record.
+        if (live.driverExit || live.finalizeOnce || live.integrityFailure)
+            return null;
+        if (!live.collector.available)
+            return null;
+        // Flush pending bytes first so the snapshot sequence always names the last
+        // published event the buffer already contains.
+        this.publishPtyData(live);
         return {
             sessionId,
             ref,
             sequence: live.rawSequence,
-            buffer: live.rawBuffer,
+            buffer: live.rawBuffer.slice(-PTY_RAW_REPLAY_CHARS),
             size: live.collector.currentSize(),
         };
     }
@@ -762,14 +788,18 @@ export class ShellRunProcessManager {
     onPtyData(live, data) {
         if (live.driverExit || live.finalizeOnce)
             return;
-        live.rawBuffer = `${live.rawBuffer}${data}`.slice(-PTY_RAW_REPLAY_CHARS);
+        // Amortize the tail trim: slicing on every tiny node-pty event copies the
+        // whole 16K replay buffer per event.
+        live.rawBuffer += data;
+        if (live.rawBuffer.length > PTY_RAW_REPLAY_CHARS * 2) {
+            live.rawBuffer = live.rawBuffer.slice(-PTY_RAW_REPLAY_CHARS);
+        }
         live.collector.accept(data);
         for (const chunk of splitPtyData(data)) {
             const combined = `${live.pendingRawData}${chunk}`;
             if (live.pendingRawData && encodedPtyDataBytes(combined) > PTY_RAW_PUBLISH_MAX_BYTES) {
                 this.publishPtyData(live);
             }
-            live.rawSequence += 1;
             live.pendingRawData += chunk;
             if (encodedPtyDataBytes(live.pendingRawData) >= PTY_RAW_PUBLISH_TARGET_BYTES) {
                 this.publishPtyData(live);
@@ -791,6 +821,7 @@ export class ShellRunProcessManager {
         if (!data)
             return;
         live.pendingRawData = '';
+        live.rawSequence += 1;
         const event = {
             sessionId: live.sessionId,
             ref: shellRunResourceRef(live.shellRunId),

package/node_modules/@maka/runtime/dist/shell-run-tool-result.js

@@ -17,7 +17,7 @@
  * under the License.
  */
 import { encodedTerminalInputActionsByteLength } from '@maka/core/terminal-input';
-import { isActiveShellRunStatus } from '@maka/core/shell-run';
+import { isActiveShellRunStatus, isDesktopTerminalShellRun } from '@maka/core/shell-run';
 import { shellRunResourceRef } from './shell-run-contract.js';
 import { truncateToolOutput } from './tool-output.js';
 import { isLikelySandboxDenial } from './sandbox/detect.js';
@@ -29,7 +29,9 @@ export function shellRunUpdate(record) {
         ownership: { kind: 'local' },
         sourceTurnId: record.sourceTurnId,
         sourceToolCallId: record.sourceToolCallId,
-        result: shellRunSnapshotContent(record),
+        result: isDesktopTerminalShellRun({ ...record, mode: record.output.mode })
+            ? shellRunStateContent(record)
+            : shellRunSnapshotContent(record),
     };
 }
 export function terminalContent(record) {

package/node_modules/@maka/runtime-host/dist/protocol/index.js

@@ -62,7 +62,9 @@ export const RUNTIME_HOST_REGISTRATION_SCHEMA_VERSION = 1;
 export const RUNTIME_HOST_PROTOCOL_VERSION = 0;
 // Increment when the same protocol version no longer guarantees safe Client-Host
 // interoperability. Mismatches are rejected before domain commands are admitted.
-export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 161;
+export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 162;
+// 162: Runtime Resource control and stop replies drop the unused resource
+// snapshot; start replies allow compact state. Older peers require snapshots.
 // 161: Session transcript reads return the whole transcript under a byte budget,
 // and every page says whether it stops between two Turns. The windowed read's
 // range edges are gone, and the Turn landmark query takes a Turn to look up, so

package/node_modules/@maka/runtime-host/dist/protocol/runtime-resource.js

@@ -111,7 +111,7 @@ export function decodeRuntimeResourceStartInput(value) {
 }
 export function decodeRuntimeResourceStartResult(value) {
     const result = requireExactRecord(value, 'Runtime Resource start result', ['resource']);
-    const decoded = { resource: decodeRuntimeResourceSnapshot(result.resource) };
+    const decoded = { resource: decodeRuntimeResourceState(result.resource) };
     requireEncodedByteLimit(decoded, 'Runtime Resource start result', RUNTIME_RESOURCE_RESULT_MAX_BYTES);
     return decoded;
 }
@@ -268,15 +268,11 @@ export function decodeRuntimeResourceControllerControlResult(value) {
     const result = requireExactRecord(value, 'Runtime Resource controller control result', [
         'controllerId',
         'sequence',
-        'resource',
     ]);
-    const decoded = {
+    return {
         controllerId: requireEntityId(result.controllerId, 'controllerId'),
         sequence: controlSequence(result.sequence, 'controller sequence'),
-        resource: decodeRuntimeResourceSnapshot(result.resource),
     };
-    requireEncodedByteLimit(decoded, 'Runtime Resource controller control result', RUNTIME_RESOURCE_RESULT_MAX_BYTES);
-    return decoded;
 }
 export function decodeRuntimeResourceControllerReleaseInput(value) {
     return decodeControllerIdentity(value, 'Runtime Resource controller release input');
@@ -302,10 +298,8 @@ export function decodeRuntimeResourceStopInput(value) {
     };
 }
 export function decodeRuntimeResourceStopResult(value) {
-    const result = requireExactRecord(value, 'Runtime Resource stop result', ['resource']);
-    const decoded = { resource: decodeRuntimeResourceSnapshot(result.resource) };
-    requireEncodedByteLimit(decoded, 'Runtime Resource stop result', RUNTIME_RESOURCE_RESULT_MAX_BYTES);
-    return decoded;
+    requireExactRecord(value, 'Runtime Resource stop result', []);
+    return {};
 }
 export function decodeRuntimeResourceUpdate(value) {
     const update = requireExactRecord(value, 'Runtime Resource update', [
@@ -332,13 +326,6 @@ export function decodeRuntimeResourceState(value) {
     }
     return decoded.content;
 }
-export function decodeRuntimeResourceSnapshot(value) {
-    const decoded = decodeRuntimeResourceState(value);
-    if (decoded.output === undefined) {
-        throw invalidProtocolFrame('Invalid Runtime Resource snapshot');
-    }
-    return decoded;
-}
 function decodeControllerIdentity(value, label) {
     const input = requireExactRecord(value, label, ['sessionId', 'ref', 'controllerId']);
     return {

package/node_modules/@maka/runtime-host/dist/server/external-session-coordinator.js

@@ -18,6 +18,7 @@
  */
 import { JsonArrayPageBudget } from './json-array-page-budget.js';
 import { ExternalSessionCatalogCursorError, ExternalSessionLimitError, ExternalSessionNotFoundError, } from '@maka/core/external-session';
+import { redactSecrets } from '@maka/core/redaction';
 import { ExternalSessionImporter } from '@maka/storage/external-sessions';
 import { EXTERNAL_SESSION_CWD_MAX_BYTES, EXTERNAL_SESSION_IMPORTED_SESSION_IDS_MAX_ITEMS, EXTERNAL_SESSION_NAME_MAX_BYTES, EXTERNAL_SESSION_PAGE_MAX_ITEMS, EXTERNAL_SESSION_RESULT_MAX_BYTES, EXTERNAL_SESSION_SOURCE_MAX_ITEMS, EXTERNAL_SESSION_SOURCE_SESSION_ID_MAX_BYTES, } from '../protocol/index.js';
 import { projectSessionCatalogRecord, SessionOperationFailure, NoUsableImportModelError, } from './session-catalog-coordinator.js';
@@ -70,7 +71,14 @@ export class HostExternalSessionCoordinator {
         const headers = await this.#sessions.listHeaders();
         for (const header of headers) {
             if (header.transcriptLedgerVersion === 0) {
-                await this.#prepareStagedSession(header.id);
+                try {
+                    await this.#prepareStagedSession(header.id);
+                }
+                catch (error) {
+                    // One staged Session can remain unpublished for a later recovery
+                    // attempt without preventing unrelated Sessions or Host startup.
+                    console.error(`[runtime-host] staged import recovery deferred (${header.id}): ${redactSecrets(error instanceof Error ? error.message : String(error))}`);
+                }
             }
         }
     }

package/node_modules/@maka/runtime-host/dist/server/runtime-resource-coordinator.js

@@ -19,12 +19,13 @@
 import { createHash } from 'node:crypto';
 import { userInfo } from 'node:os';
 import { isActiveShellRunStatus } from '@maka/core/shell-run';
+import { shellRunStateProjection } from '@maka/core/shell-run-result';
 import { ShellRunPtyControlClosedError, isShellRunResourceRef, } from '@maka/runtime/shell-run-contract';
 import { defaultShellPlan, ShellPreferenceError } from '@maka/runtime/shell-detect';
 import { isSessionNotFoundError } from '@maka/storage/execution-stores';
 import { decodeRuntimeResourceControllerAcquireResult, decodeRuntimeResourceControllerControlResult, decodeRuntimeResourceQueryResult, decodeRuntimeResourceStopResult, decodeRuntimeResourceStartResult, RUNTIME_RESOURCE_CONTROLLER_ACQUIRE_RESULT_MAX_BYTES, RUNTIME_RESOURCE_MAX_CONTROL_SEQUENCE, } from '../protocol/index.js';
 import { boundedFailureDiagnostic } from './failure-diagnostic.js';
-import { boundedRuntimeResourceSnapshot, canonicalRuntimeResources, createRuntimeResourcePage, runtimeResourceRevision, runtimeResourceSnapshotFromResult, } from './runtime-resource-projection.js';
+import { boundedRuntimeResourceState, canonicalRuntimeResources, createRuntimeResourcePage, runtimeResourceRevision, } from './runtime-resource-projection.js';
 const MAX_CONTROL_REPLAYS = 128;
 /** Owns Host Shell/PTY tools plus the connection-scoped Client controller fence. */
 export class HostRuntimeResourceCoordinator {
@@ -347,22 +348,22 @@ export class HostRuntimeResourceCoordinator {
                     return {
                         ok: true,
                         result: decodeRuntimeResourceStartResult({
-                            resource: boundedRuntimeResourceSnapshot(await this.#manager.inspectResource(input.sessionId, launched.ref)),
+                            resource: boundedRuntimeResourceState(shellRunStateProjection(launched)),
                         }),
                     };
                 }
-                catch (inspectError) {
+                catch (replyError) {
                     // The command is already live but the operation must not report a
                     // success it cannot honor: stop it so a client retry cannot
                     // double-execute (#3210 review). Best-effort — the surfaced error
-                    // stays the inspection failure.
+                    // stays the reply failure.
                     try {
                         await this.#manager.stopBackgroundTask(input.sessionId, launched.ref, new AbortController().signal, 'client');
                     }
                     catch {
-                        /* keep the inspection failure as the surfaced cause */
+                        /* keep the reply failure as the surfaced cause */
                     }
-                    throw inspectError;
+                    throw replyError;
                 }
             });
         }
@@ -388,8 +389,11 @@ export class HostRuntimeResourceCoordinator {
             if (sessionFailure)
                 return mutationFailure('runtime.resource.controller.acquire', sessionFailure);
             try {
-                const snapshot = await this.#manager.inspectResource(input.sessionId, input.ref);
-                if (snapshot.mode !== 'pty' || !isActiveShellRunStatus(snapshot.status)) {
+                const pty = this.#manager.getLivePtySnapshot(input.sessionId, input.ref);
+                if (!pty) {
+                    // No live handle: read through the manager so a stale active record
+                    // is repaired to orphaned; the reply is a conflict either way.
+                    await this.#manager.inspectResource(input.sessionId, input.ref);
                     return mutationFailure('runtime.resource.controller.acquire', {
                         code: 'operation_conflict',
                         message: 'Only an active PTY Runtime Resource can be controlled',
@@ -420,14 +424,6 @@ export class HostRuntimeResourceCoordinator {
                 };
                 this.#controllers.set(key, controller);
                 this.#controllerResources.set(identity, key);
-                const pty = this.#manager.getLivePtySnapshot(input.sessionId, input.ref);
-                if (!pty) {
-                    this.#releaseController(key);
-                    return mutationFailure('runtime.resource.controller.acquire', {
-                        code: 'operation_conflict',
-                        message: 'Runtime Resource PTY is no longer available',
-                    });
-                }
                 return {
                     ok: true,
                     result: boundedControllerAcquireResult(controller.controllerId, controller.nextSequence, pty),
@@ -485,7 +481,6 @@ export class HostRuntimeResourceCoordinator {
                 const result = decodeRuntimeResourceControllerControlResult({
                     controllerId: input.controllerId,
                     sequence: input.sequence,
-                    resource: boundedRuntimeResourceSnapshot(runtimeResourceSnapshotFromResult(controlled)),
                 });
                 this.#rememberReplay({
                     connectionId: context.connectionId,
@@ -555,12 +550,7 @@ export class HostRuntimeResourceCoordinator {
             try {
                 const result = await this.#manager.stopBackgroundTask(input.sessionId, input.ref, new AbortController().signal, 'client');
                 this.#releaseControllerIfTerminal(input.sessionId, input.ref, result);
-                return {
-                    ok: true,
-                    result: decodeRuntimeResourceStopResult({
-                        resource: boundedRuntimeResourceSnapshot(runtimeResourceSnapshotFromResult(result)),
-                    }),
-                };
+                return { ok: true, result: decodeRuntimeResourceStopResult({}) };
             }
             catch (error) {
                 return this.#resourceFailure('runtime.resource.stop', error);

package/node_modules/@maka/runtime-host/dist/server/runtime-resource-projection.js

@@ -28,8 +28,11 @@ export function canonicalRuntimeResources(resources) {
         left.sourceToolCallId.localeCompare(right.sourceToolCallId));
 }
 function boundedRuntimeResourceUpdate(update) {
-    const bounded = structuredClone(update);
-    shrinkStateToFit(bounded.result);
+    return { ...update, result: boundedRuntimeResourceState(update.result) };
+}
+export function boundedRuntimeResourceState(state) {
+    const bounded = structuredClone(state);
+    shrinkStateToFit(bounded);
     return bounded;
 }
 export function runtimeResourceRevision(resources) {
@@ -68,20 +71,6 @@ export function createRuntimeResourcePage(sessionId, revision, resources, offset
         nextCursor: nextOffset < resources.length ? String(nextOffset) : null,
     });
 }
-export function boundedRuntimeResourceSnapshot(snapshot) {
-    const bounded = structuredClone(snapshot);
-    shrinkStateToFit(bounded);
-    if (bounded.output === undefined)
-        throw new Error('Runtime Resource snapshot lost its output');
-    return bounded;
-}
-export function runtimeResourceSnapshotFromResult(result) {
-    if (result.kind !== 'shell_run' || result.output === undefined) {
-        throw new Error('Runtime Resource operation did not produce a ShellRun snapshot');
-    }
-    const { operation: _operation, ...snapshot } = result;
-    return snapshot;
-}
 function shrinkStateToFit(state) {
     while (Buffer.byteLength(JSON.stringify(state), 'utf8') > RUNTIME_RESOURCE_SNAPSHOT_MAX_BYTES) {
         const fields = mutableTextFields(state).sort((left, right) => Buffer.byteLength(right.value(), 'utf8') - Buffer.byteLength(left.value(), 'utf8'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maka-agent",
-  "version": "0.2.0-dev.40.20260917",
+  "version": "0.2.0-dev.41.20260918",
   "description": "Apache Maka (Incubating) developer snapshot; not an Apache release.",
   "license": "Apache-2.0",
   "type": "module",