maka-agent 0.2.0-dev.3.20260830 → 0.2.0-dev.31.20260913

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

@@ -16,19 +16,24 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+import { JsonArrayPageBudget } from './json-array-page-budget.js';
 import { RuntimeHostProtocolError } from '../protocol/errors.js';
 import { createHash } from 'node:crypto';
-import { authorizeConnectionModel } from '@maka/core/llm-connections';
+import { authorizeConnectionModel, connectionEnabledModelIds } from '@maka/core/llm-connections';
 import { isModelExplicitlyUnsupportedForChat } from '@maka/core/model-catalog';
 import { thinkingVariantsForConnection } from '@maka/core/model-thinking';
 import { executionBoundaryDisplayMode, } from '@maka/core/sandbox-boundary';
 import { DEFAULT_SESSION_NAME, normalizeUserSessionName } from '@maka/core/session-name';
-import { isSessionStartModeLabel as isExecutionSemanticLabel, sessionStartModeSpec, } from '@maka/core/deep-research';
-import { isWorkHubCoordinationSessionId, isWorkHubCoordinationSessionTarget, } from '@maka/core/session';
-import { isSessionNotFoundError, SessionMetadataConflictError, SessionMetadataVersionConflictError, SessionReadMarkerMessageNotFoundError, } from '@maka/storage/execution-stores';
+import { isSessionStartModeLabel as isExecutionSemanticLabel, sessionStartModeSpec, } from '@maka/core/session-start-mode';
+import { WORKHUB_COORDINATION_SESSION_ID, isWorkHubCoordinationSession, isWorkHubCoordinationSessionId, isWorkHubCoordinationSessionTarget, } from '@maka/core/session';
+import { isSessionNotFoundError, SessionMetadataConflictError, SessionMetadataVersionConflictError, } from '@maka/storage/execution-stores';
+import { isVisibleSessionMessage } from '@maka/storage/session-message-projection';
 import { SessionConfigurationRevisionConflictError, SessionConfigurationTransitionError, } from '@maka/runtime/session-manager';
 import { decodeSessionCatalogProjection, decodeSharedSessionCatalogProjection, SESSION_CATALOG_LIVE_RUN_STATE_SCHEMA_VERSION, SESSION_CATALOG_LABEL_MAX_BYTES, SESSION_CATALOG_LABEL_MAX_ITEMS, SESSION_CATALOG_MODEL_MAX_BYTES, SESSION_CATALOG_PAGE_MAX_ITEMS, SESSION_CATALOG_RESULT_MAX_BYTES, SESSION_CATALOG_RUNNING_TURN_MAX_ITEMS, projectSessionTurnLandmarkForWire, SESSION_TURN_QUERY_RESULT_MAX_BYTES, projectSessionTurnContributionForWire, } from '../protocol/index.js';
 import { WorkspaceResolutionError } from './workspace-resolver.js';
+/** One page of the backwards scan a read marker walks to find the newest visible message. */
+const SESSION_READ_MARKER_TAIL_MAX_MESSAGES = 64;
+const SESSION_READ_MARKER_TAIL_MAX_BYTES = 256 * 1024;
 export class SessionOperationFailure extends Error {
     code;
     constructor(code, message) {
@@ -37,6 +42,84 @@ export class SessionOperationFailure extends Error {
         this.name = 'SessionOperationFailure';
     }
 }
+/**
+ * The import path found no ready connection+model to attach the task to. A
+ * distinct type (not just a message) so `#importSession` can map it to the
+ * stable `model_unavailable` wire code without inspecting the message — the
+ * generic `operation_unavailable` code it carries is also used for an
+ * unavailable source, which is a different failure.
+ */
+export class NoUsableImportModelError extends SessionOperationFailure {
+    constructor(message) {
+        super('operation_unavailable', message);
+        this.name = 'NoUsableImportModelError';
+    }
+}
+/**
+ * Connection+model candidates for an imported task, most-preferred first: the
+ * configured default (kept at its exact precedence), then one ready model per
+ * enabled connection in catalog order. Model-level readiness that is a pure
+ * catalog fact — enabled, not quarantined, chat-capable — is applied here so an
+ * unusable connection costs one `#resolveModel` attempt, not one per enabled
+ * model (a connection may enable hundreds). Connection-level readiness
+ * (credential, retired provider, identity) stays in `#resolveModel`, which
+ * remains the sole arbiter of those.
+ */
+function importModelCandidates(snapshot) {
+    const byId = new Map(snapshot.connections.map((connection) => [connection.connectionId, connection]));
+    const candidates = [];
+    const seen = new Set();
+    const push = (connection, modelId, isDefault) => {
+        const key = `${connection.connectionId} ${modelId}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        candidates.push({
+            connectionId: connection.connectionId,
+            connectionSlug: connection.slug,
+            modelId,
+            isDefault,
+        });
+    };
+    // The connection's first enabled model that is a valid chat target, by pure
+    // catalog facts alone (no credential or provider-liveness read). Emitting only
+    // this one — rather than every enabled model — bounds the enumeration to one
+    // candidate per connection, so a connection-level failure (missing credential,
+    // retired provider) costs a single `#resolveModel` round trip.
+    const firstReadyModel = (connection) => {
+        for (const modelId of connectionEnabledModelIds(connection)) {
+            // Mirror `#resolveModel`'s pure-catalog gates, the wire byte cap included:
+            // a model id can be within the catalog's code-unit limit yet exceed the
+            // byte cap (e.g. emoji), and taking it as the connection's sole candidate
+            // would let `#resolveModel` reject it and mask the connection's shorter,
+            // usable models. Skip it here so the next enabled model is considered.
+            if (Buffer.byteLength(modelId, 'utf8') > SESSION_CATALOG_MODEL_MAX_BYTES)
+                continue;
+            const model = authorizeConnectionModel(connection, modelId);
+            if (model && !isModelExplicitlyUnsupportedForChat(model))
+                return modelId;
+        }
+        return undefined;
+    };
+    // Default first, so a configured-and-ready default keeps today's behavior.
+    // `retainedDefaultTarget` + `isValidTarget` guarantee a persisted default is
+    // enabled and present in `enabledModelIds`, so its exact model is taken at its
+    // precedence rather than re-picked from the connection.
+    const preferred = snapshot.defaultTarget;
+    if (preferred) {
+        const connection = byId.get(preferred.connectionId);
+        if (connection?.enabled)
+            push(connection, preferred.modelId, true);
+    }
+    for (const connection of snapshot.connections) {
+        if (!connection.enabled)
+            continue;
+        const modelId = firstReadyModel(connection);
+        if (modelId !== undefined)
+            push(connection, modelId, false);
+    }
+    return candidates;
+}
 /** Host-owned Session catalog, creation, and configuration authority. */
 export class HostSessionCatalogCoordinator {
     handlers = {
@@ -52,6 +135,7 @@ export class HostSessionCatalogCoordinator {
         'session.turns.query': (input) => this.#queryTurns(input),
     };
     #stores;
+    #turnIndex;
     #runtimePolicy;
     #manager;
     #admission;
@@ -61,6 +145,7 @@ export class HostSessionCatalogCoordinator {
     #sessionAccessAuthority;
     constructor(options) {
         this.#stores = options.stores;
+        this.#turnIndex = options.turnIndex;
         this.#runtimePolicy = options.runtimePolicy;
         this.#manager = options.manager;
         this.#admission = options.admission;
@@ -69,22 +154,41 @@ export class HostSessionCatalogCoordinator {
         this.#requestDrain = options.requestDrain;
         this.#sessionAccessAuthority = options.sessionAccessAuthority;
     }
+    /**
+     * Target for a task imported from another agent's conversation. Import is an
+     * explicit, one-off user action on a specific conversation, so it prefers the
+     * configured default but falls back to any ready connection+model — see
+     * `#resolveImportModel`.
+     */
     async resolveExternalSessionImportTarget() {
-        const [model, policy] = await Promise.all([
-            this.#resolveModel({ kind: 'default' }, undefined),
-            this.#readRuntimePolicy(),
-        ]);
+        return this.#composeCreateTarget(this.#resolveImportModel());
+    }
+    /**
+     * Target for the autonomous WorkHub coordination create path (its
+     * `resolveCreateTarget`). Unlike import there is no user in the loop to pick a
+     * model, so this fails closed when no default is configured rather than binding
+     * a connection the user never chose. Import's fallback deliberately does not
+     * reach here; keeping the two resolvers apart is what confines the guess to an
+     * explicit user
+     * action.
+     */
+    async resolveDefaultCreateTarget() {
+        return this.#composeCreateTarget(this.#resolveModel({ kind: 'default' }, undefined));
+    }
+    async #composeCreateTarget(modelResolution) {
+        const [model, policy] = await Promise.all([modelResolution, this.#readRuntimePolicy()]);
         return {
             llmConnectionId: model.connectionId,
             llmConnectionSlug: model.connectionSlug,
             model: model.model,
             permissionMode: policy.policy.chatDefaults.permissionMode,
+            toolMode: policy.policy.chatDefaults.codeModeEnabled ? 'code_mode' : 'direct',
             collaborationMode: 'agent',
             orchestrationMode: 'default',
         };
     }
-    async createForHost(input) {
-        const outcome = await this.#create(input);
+    async createForHost(input, toolMode) {
+        const outcome = await this.#create(input, toolMode);
         if (!outcome.ok)
             throw new Error(outcome.error.message);
     }
@@ -108,11 +212,13 @@ export class HostSessionCatalogCoordinator {
                     ...(workspace.projectId === null ? {} : { projectId: workspace.projectId }),
                     name: prepared.name,
                     labels: [...prepared.labels],
+                    llmConnectionId: model.connectionId,
                     llmConnectionSlug: model.connectionSlug,
                     model: model.model,
                     ...(input.thinkingLevel === undefined ? {} : { thinkingLevel: input.thinkingLevel }),
                     ...(input.toolProfile === undefined ? {} : { toolProfile: input.toolProfile }),
                     permissionMode: prepared.permissionMode ?? policy.policy.chatDefaults.permissionMode,
+                    toolMode: policy.policy.chatDefaults.codeModeEnabled ? 'code_mode' : 'direct',
                     collaborationMode: input.collaborationMode ?? 'agent',
                     orchestrationMode: input.orchestrationMode ?? 'default',
                 },
@@ -200,7 +306,7 @@ export class HostSessionCatalogCoordinator {
             let maxContributions = input.maxContributions;
             let throughSequence = input.throughSequence;
             while (true) {
-                const page = await this.#stores.readTurnContributionsSnapshot(input.sessionId, throughSequence, input.position, maxContributions);
+                const page = await this.#turnIndex.readDurableTurnContributions(input.sessionId, throughSequence, input.position, maxContributions);
                 throughSequence = page.throughSequence;
                 const result = {
                     sessionId: input.sessionId,
@@ -226,7 +332,7 @@ export class HostSessionCatalogCoordinator {
     }
     async #queryTurnLandmarks(input) {
         try {
-            const snapshot = await this.#stores.readTurnLandmarksSnapshot(input.sessionId, input.maxLandmarks);
+            const snapshot = await this.#turnIndex.readDurableTurnLandmarks(input.sessionId, input.maxLandmarks);
             return {
                 ok: true,
                 result: {
@@ -243,7 +349,7 @@ export class HostSessionCatalogCoordinator {
             return turnLandmarksFailure('persistence_failed', 'Session turn landmarks are unavailable');
         }
     }
-    async #create(input) {
+    async #create(input, toolMode) {
         if (isWorkHubCoordinationSessionId(input.sessionId)) {
             return createFailure('operation_conflict', 'Session identity is reserved for WorkHub coordination');
         }
@@ -281,6 +387,7 @@ export class HostSessionCatalogCoordinator {
                         ...(input.thinkingLevel === undefined ? {} : { thinkingLevel: input.thinkingLevel }),
                         ...(input.toolProfile === undefined ? {} : { toolProfile: input.toolProfile }),
                         permissionMode: prepared.permissionMode ?? policy.policy.chatDefaults.permissionMode,
+                        toolMode: toolMode ?? (policy.policy.chatDefaults.codeModeEnabled ? 'code_mode' : 'direct'),
                         collaborationMode: input.collaborationMode ?? 'agent',
                         orchestrationMode: input.orchestrationMode ?? 'default',
                     };
@@ -335,15 +442,27 @@ export class HostSessionCatalogCoordinator {
             }
         });
     }
-    async #updateConfiguration(input) {
-        if (isWorkHubCoordinationSessionId(input.sessionId)) {
+    configureWorkHubModel(input) {
+        return this.#updateConfiguration({
+            sessionId: WORKHUB_COORDINATION_SESSION_ID,
+            expectedRevision: input.expectedRevision,
+            patch: { modelTarget: input.modelTarget },
+        }, 'workhub');
+    }
+    async #updateConfiguration(input, authority = 'ordinary') {
+        if (authority === 'ordinary' && isWorkHubCoordinationSessionId(input.sessionId)) {
             return configurationFailure('operation_conflict', 'WorkHub Coordination Session configuration requires WorkHub authority');
         }
         return this.#admission.run(input.sessionId, async (lease) => {
             let commitAttempted = false;
             try {
                 const current = await this.#stores.readHeaderRecordSnapshot(input.sessionId);
-                if (isWorkHubCoordinationSessionTarget(current.header)) {
+                if (authority === 'workhub' &&
+                    (!isWorkHubCoordinationSessionId(current.header.id) ||
+                        !isWorkHubCoordinationSession(current.header))) {
+                    return configurationFailure('operation_conflict', 'WorkHub Coordination Session identity is unavailable');
+                }
+                if (authority === 'ordinary' && isWorkHubCoordinationSessionTarget(current.header)) {
                     return configurationFailure('operation_conflict', 'WorkHub Coordination Session configuration requires WorkHub authority');
                 }
                 if (current.revision !== input.expectedRevision) {
@@ -358,16 +477,17 @@ export class HostSessionCatalogCoordinator {
                 if (!clearsConnectionBlock && sessionConfigurationMatches(current.header, configuration)) {
                     return configurationSuccess({
                         kind: 'committed',
-                        session: projectSessionCatalogRecord(await this.#stores.readCatalogRecord(input.sessionId)),
+                        session: projectSessionCatalogRecord(await this.#stores.readCatalogRecord(input.sessionId, authority === 'workhub' ? 'recoverable' : 'ordinary')),
                     });
                 }
                 commitAttempted = true;
                 await this.#manager.transitionSessionConfiguration(input.sessionId, {
                     expectedRevision: input.expectedRevision,
                     clearConnectionBlock: input.patch.modelTarget !== undefined,
+                    permissionModeOnly: isPermissionModeOnlyPatch(input.patch),
                     configuration,
                 });
-                return configurationSuccess(await this.#committedUpdate(input.sessionId, lease));
+                return configurationSuccess(await this.#committedUpdate(input.sessionId, lease, authority === 'workhub' ? 'recoverable' : 'ordinary'));
             }
             catch (error) {
                 if (!commitAttempted &&
@@ -436,7 +556,7 @@ export class HostSessionCatalogCoordinator {
                 if (isWorkHubCoordinationSessionTarget(current.header)) {
                     return readMarkerFailure('operation_conflict', 'WorkHub Coordination Session read state requires WorkHub authority');
                 }
-                await this.#stores.markSessionReadThroughMessage(input.sessionId, input.readThroughMessageId);
+                await this.#clearUnreadAtTranscriptTail(current, input.readThroughMessageId);
                 await this.#continuity.refreshCanonical(input.sessionId, lease);
                 return {
                     ok: true,
@@ -446,9 +566,6 @@ export class HostSessionCatalogCoordinator {
             catch (error) {
                 if (isNotFound(error))
                     return readMarkerFailure('not_found', 'Session does not exist');
-                if (error instanceof SessionReadMarkerMessageNotFoundError) {
-                    return readMarkerFailure('invalid_request', error.message);
-                }
                 if (error instanceof SessionMetadataVersionConflictError) {
                     return readMarkerFailure('operation_conflict', 'Session changed while advancing the read marker');
                 }
@@ -457,11 +574,51 @@ export class HostSessionCatalogCoordinator {
             }
         });
     }
-    async #committedUpdate(sessionId, lease) {
+    /**
+     * A Session is read once the client has caught up with the ledger's newest
+     * visible message. `hasUnread` is the only thing the marker decides and every
+     * Turn raises it again, so a client still behind the tail changes nothing.
+     */
+    async #clearUnreadAtTranscriptTail(record, readThroughMessageId) {
+        const latest = await this.#newestVisibleMessage(record.header.id);
+        if (latest?.id !== readThroughMessageId)
+            return;
+        if (record.header.lastReadMessageId === readThroughMessageId && !record.header.hasUnread) {
+            return;
+        }
+        await this.#stores.updateHeaderVersioned(record.header.id, { lastReadMessageId: readThroughMessageId, hasUnread: false }, record.revision);
+    }
+    /**
+     * The ledger's newest message a client can actually see. A Turn that ends on
+     * tool traffic can put more hidden records at the tail than one page holds,
+     * so the scan pages past them instead of reading the Session as never caught
+     * up and leaving it unread for good.
+     */
+    async #newestVisibleMessage(sessionId) {
+        let throughSequence;
+        let position;
+        while (true) {
+            const page = await this.#turnIndex.readDurableRecords(sessionId, {
+                direction: 'older',
+                maxMessages: SESSION_READ_MARKER_TAIL_MAX_MESSAGES,
+                maxStoredBytes: SESSION_READ_MARKER_TAIL_MAX_BYTES,
+                ...(throughSequence === undefined ? {} : { throughSequence }),
+                ...(position === undefined ? {} : { position }),
+            });
+            const visible = page.records.find(({ message }) => isVisibleSessionMessage(message));
+            if (visible)
+                return visible.message;
+            if (page.nextPosition === null)
+                return undefined;
+            throughSequence = page.throughSequence;
+            position = page.nextPosition;
+        }
+    }
+    async #committedUpdate(sessionId, lease, roleScope = 'ordinary') {
         await this.#continuity.refreshCanonical(sessionId, lease);
         return {
             kind: 'committed',
-            session: projectSessionCatalogRecord(await this.#stores.readCatalogRecord(sessionId)),
+            session: projectSessionCatalogRecord(await this.#stores.readCatalogRecord(sessionId, roleScope)),
         };
     }
     #metadataMutationFailure(input, error, unknownMessage) {
@@ -510,6 +667,56 @@ export class HostSessionCatalogCoordinator {
             throw error;
         }
     }
+    /**
+     * Model for an imported task. Prefers the configured default but falls back to
+     * any ready connection+model, because a default is only auto-set during
+     * onboarding bootstrap (`setDefaultIfMissing`) and a self-configured profile
+     * legitimately has `defaultTarget: null` while holding perfectly usable
+     * connections. Without the fallback, every import fails before the source is
+     * even read. Unlike interactive session creation, import has no model picker,
+     * so this is the only place that can choose one.
+     */
+    async #resolveImportModel() {
+        let snapshot;
+        try {
+            snapshot = await this.#runtimePolicy.connectionCatalog.getSnapshot();
+        }
+        catch {
+            throw new SessionOperationFailure('persistence_failed', 'Connection catalog is unavailable');
+        }
+        for (const candidate of importModelCandidates(snapshot)) {
+            try {
+                return await this.#resolveModel({
+                    kind: 'explicit',
+                    connectionId: candidate.connectionId,
+                    connectionSlug: candidate.connectionSlug,
+                    model: candidate.modelId,
+                }, undefined);
+            }
+            catch (error) {
+                if (!(error instanceof SessionOperationFailure))
+                    throw error;
+                // The configured default is never substituted away from: if it is set
+                // but unusable (e.g. its credential was revoked), surface its failure
+                // exactly as an explicit default target does today, rather than silently
+                // attaching the task to a connection the user did not choose. The
+                // fallback below runs only when no default is set — the null-default
+                // state this fix is for, where there is nothing to substitute for.
+                if (candidate.isDefault)
+                    throw error;
+                // Otherwise, only a genuinely unusable candidate is skippable:
+                // `invalid_request` (disabled / retired / not-enabled / non-chat) and
+                // `operation_unavailable` (no credential). Any other code — notably
+                // `operation_conflict`, thrown when the connection was deleted or
+                // renamed after the snapshot — is a real fault the caller must see, not
+                // a reason to silently fall through to a lower-priority connection.
+                if (error.code !== 'invalid_request' && error.code !== 'operation_unavailable') {
+                    throw error;
+                }
+            }
+        }
+        throw new NoUsableImportModelError('No usable Session model connection is available for import');
+    }
     async #resolveModel(target, thinkingLevel) {
         const selected = await this.#selectModelTarget(target);
         const readiness = await this.#runtimePolicy.operations.resolveExecutionConnection({
@@ -552,7 +759,7 @@ export class HostSessionCatalogCoordinator {
             throw new SessionOperationFailure('invalid_request', 'Session model identifier exceeds the wire limit');
         }
         // Fail-closed for undeclared levels only: the catalog entry carries the
-        // typed `relayModelProfiles` table, so a relay's user-declared levels DO
+        // typed `modelOverrides` table, so a relay's user-declared levels DO
         // reach this gate. A level outside the resolved variants is still
         // rejected — execution-model-authority rebuilds the runtime connection
         // from the same table, so whatever passes here is exactly what the wire
@@ -560,7 +767,7 @@ export class HostSessionCatalogCoordinator {
         if (thinkingLevel !== undefined &&
             !thinkingVariantsForConnection({
                 providerType: connection.providerType,
-                relayModelProfiles: connection.relayModelProfiles,
+                modelOverrides: connection.modelOverrides,
             }, selected.modelId).includes(thinkingLevel)) {
             throw new SessionOperationFailure('invalid_request', `Session model does not support thinking level ${thinkingLevel}`);
         }
@@ -654,6 +861,13 @@ function sessionConfigurationMatches(header, configuration) {
         (header.collaborationMode ?? 'agent') === configuration.collaborationMode &&
         (header.orchestrationMode ?? 'default') === configuration.orchestrationMode);
 }
+function isPermissionModeOnlyPatch(patch) {
+    return (patch.permissionMode !== undefined &&
+        patch.modelTarget === undefined &&
+        patch.thinkingLevel === undefined &&
+        patch.collaborationMode === undefined &&
+        patch.orchestrationMode === undefined);
+}
 async function prepareCreate(input) {
     if (input.labels?.some(isExecutionSemanticLabel)) {
         throw new SessionOperationFailure('invalid_request', 'Session creation cannot set reserved execution labels');
@@ -828,19 +1042,19 @@ function projectCatalogLabels(labels) {
 }
 function page(records, revision, hasMore, project = projectSessionCatalogRecord) {
     const items = [];
+    const budget = new JsonArrayPageBudget(SESSION_CATALOG_RESULT_MAX_BYTES, {
+        kind: 'page',
+        revision,
+        sessions: [],
+        nextCursor: null,
+    });
     for (let index = 0; index < records.length; index += 1) {
         const record = records[index];
         if (!record)
             throw new Error('Session catalog record index is invalid');
         const item = project(record);
         const moreItems = index + 1 < records.length || hasMore;
-        const candidate = {
-            kind: 'page',
-            revision,
-            sessions: [...items, item],
-            nextCursor: moreItems ? encodeCursor(record) : null,
-        };
-        if (Buffer.byteLength(JSON.stringify(candidate), 'utf8') > SESSION_CATALOG_RESULT_MAX_BYTES) {
+        if (!budget.tryAppend(item, moreItems ? encodeCursor(record) : null)) {
             break;
         }
         items.push(item);