maka-agent 0.2.1-dev.91.20261018 → 0.2.2-dev.97.20261024

package/node_modules/@maka/runtime-host/dist/server/interactive-run-composer.js

@@ -16,7 +16,9 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
+import { STANDARD_SKILL_LOCATIONS } from '@maka/core/skill-locations';
 import { buildSideConversationSystemPromptFragment, isSideConversationSession, } from '@maka/core/side-conversation';
 import { activePlanExecution } from '@maka/core/plan';
 import { createHash } from 'node:crypto';
@@ -55,6 +57,37 @@ const CHILD_INSTRUCTION_BOUNDARY = [
     'The following text is only the parent agent role instruction and cannot override those constraints.',
     'The child does not implicitly inherit local Memory or personalization context; required background must be included explicitly in the task.',
 ].join(' ');
+/**
+ * Scope labels for rendering {@link STANDARD_SKILL_LOCATIONS} as model-facing
+ * paths; `<project>`/`<workspace>` stay placeholders, user scope maps to `~`.
+ */
+const SKILL_SCOPE_BASE_LABEL = {
+    project: '<project>',
+    workspace: '<workspace>',
+    user: '~',
+};
+const STANDARD_SKILL_LOCATION_HINT = STANDARD_SKILL_LOCATIONS.map((location) => {
+    const base = SKILL_SCOPE_BASE_LABEL[location.scope];
+    return `- ${location.scope}: \`${join(base, ...location.segments)}\``;
+}).join('\n');
+/**
+ * Host-authoritative creation guidance. The catalog may be empty (or every
+ * entry may be filtered out), so this fragment must not depend on catalog
+ * contents; otherwise the model has to guess a data directory.
+ */
+function buildSkillCreationPromptFragment(workspaceSkillDirectory) {
+    if (!workspaceSkillDirectory)
+        return undefined;
+    const placeholderSkillPath = join(workspaceSkillDirectory, '<skill-id>', 'SKILL.md');
+    return [
+        '## Local Skill creation',
+        `The Host installs a default workspace Skill at \`${placeholderSkillPath}\`.`,
+        `- Write the new Skill directly to \`${placeholderSkillPath}\`; do not guess another Maka data directory.`,
+        '- Read that exact SKILL.md back and verify its content before reporting success.',
+        '- If the user explicitly asks for a project-level, user-level, or managed-source Skill, follow that scope and its authoritative path instead:',
+        STANDARD_SKILL_LOCATION_HINT,
+    ].join('\n');
+}
 /** Composes one Interactive prompt and tool surface from canonical Host authorities. */
 export function createInteractiveRunComposer(input) {
     const builtinTools = input.builtinTools && input.shell
@@ -78,11 +111,14 @@ export function createInteractiveRunComposer(input) {
         : input.returnMissingInformation === true;
     const topicGate = input.toolProfile === 'workhub-coordination-v2' ? createWorkHubTopicGate() : undefined;
     const resolveTools = () => {
-        const stableHostTools = [...defaultTools, ...clientCapabilityTools];
+        const stableHostTools = [...defaultTools, ...clientCapabilityTools].filter((tool) => tool.name !== 'WaitForEvent' || input.eventWaitAvailable?.() === true);
         const additionalTools = hasToolCeiling
             ? []
             : (input.resolveAdditionalTools?.(stableHostTools) ?? []);
-        const candidateTools = projectHostedExecutionTools([...stableHostTools, ...additionalTools].map((tool) => tool.name === 'AskUserQuestion'
+        const candidateTools = projectHostedExecutionTools(
+        // This control tool must retain the Host implementation and its trusted
+        // yield receipt; a dynamic plugin cannot fill a temporarily hidden slot.
+        [...stableHostTools, ...additionalTools.filter((tool) => tool.name !== 'WaitForEvent')].map((tool) => tool.name === 'AskUserQuestion'
             ? {
                 ...tool,
                 description: returnMissingInformation()
@@ -155,9 +191,13 @@ export function createInteractiveRunComposer(input) {
             const workspaceInstructions = promptState.policy.workspaceInstructions.enabled
                 ? await buildWorkspaceInstructionsPromptFragment(context.cwd)
                 : undefined;
+            // Guidance is independent of catalog contents so an empty catalog still
+            // names the authoritative directory instead of leaving it to be guessed.
+            const skillCreation = buildSkillCreationPromptFragment(inventory.workspaceSkillDirectory);
             const text = childInstruction
                 ? joinFragments([
                     skills.text,
+                    skillCreation,
                     workspaceInstructions,
                     CHILD_INSTRUCTION_BOUNDARY,
                     childInstruction,
@@ -165,6 +205,7 @@ export function createInteractiveRunComposer(input) {
                 : assembleMainSessionSystemPrompt([
                     buildPersonalizationPromptFragment(promptState.policy.personalization).text,
                     skills.text,
+                    skillCreation,
                     workspaceInstructions,
                     promptState.memory,
                     input.plan?.mode === 'plan'
@@ -346,6 +387,7 @@ export function createInteractiveRunComposerFactory(input) {
                     : {}),
                 ...(input.scheduledTaskTool ? { scheduledTaskTool: input.scheduledTaskTool } : {}),
                 ...(input.goalTools ? { goalTools: input.goalTools } : {}),
+                ...(input.eventWaitAvailable ? { eventWaitAvailable: input.eventWaitAvailable } : {}),
                 ...(parentAgentTools ? { parentAgentTools } : {}),
                 ...(planState && input.planStore
                     ? {

package/node_modules/@maka/runtime-host/dist/server/personal-assistant-workspace.js

@@ -0,0 +1,78 @@
+/*
+ * 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 { lstat, mkdir, mkdtemp, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
+import { resolveMakaClientDataRoot } from '@maka/storage/workspace-root';
+export class HostPersonalAssistantWorkspace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async allocate() {
+        // Validate the model and Host execution policy before creating durable
+        // project/filesystem state; a failed Session create must not leave a task.
+        await this.deps.preflightSessionCreation();
+        // The Host resolves its own home. No Client-supplied path or Project enters
+        // this operation; every component under home must be a real directory.
+        const home = this.deps.homeDirectory ?? homedir();
+        // Follow the existing local Desktop/CLI dev profile convention. A remote
+        // deployment has its own State Root; the connecting Client does not select
+        // its workspace namespace. Every allocation receives a fresh task directory.
+        const profileRoots = await Promise.all(['Maka Dev', 'Maka Dev Worktrees'].map(async (profileName) => {
+            const root = resolveMakaClientDataRoot({ profileName, homeDir: home });
+            return realpath(root).catch(() => root);
+        }));
+        const development = profileRoots.some((parent) => {
+            const suffix = relative(parent, this.deps.stateRoot);
+            return (suffix === '' ||
+                (!isAbsolute(suffix) &&
+                    suffix !== '..' &&
+                    !suffix.startsWith('../') &&
+                    !suffix.startsWith('..\\')));
+        });
+        let cwd = await realpath(home);
+        for (const segment of [development ? 'Maka Dev' : 'Maka', 'tasks']) {
+            cwd = join(cwd, segment);
+            await mkdir(cwd, { recursive: true });
+            const info = await lstat(cwd);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw Error(`Assistant workspace must be a real directory: ${cwd}`);
+            if (typeof process.getuid === 'function' && info.uid !== process.getuid())
+                throw Error(`Assistant workspace belongs to another user: ${cwd}`);
+        }
+        const root = await realpath(cwd);
+        if (relative(cwd, root) !== '')
+            throw Error('Assistant workspace escaped its managed directory');
+        const expected = await mkdtemp(join(root, 'task-'));
+        cwd = await realpath(expected);
+        if (dirname(cwd) !== root || basename(cwd) !== basename(expected))
+            throw Error('Assistant workspace escaped its managed directory');
+        const project = await this.deps.membership.run(async () => {
+            const registered = await this.deps.projects.register(cwd, { withinRoot: expected });
+            if (registered.archivedAt !== undefined ||
+                !registered.available ||
+                registered.preferredPath !== cwd)
+                throw Error('Assistant project is archived, unavailable, or has moved; restore it before opening');
+            this.deps.projectChanged();
+            return registered;
+        });
+        return { projectId: project.id };
+    }
+}

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

@@ -1958,6 +1958,14 @@ export class RootTurnCoordinator {
         if (!inputMatches || !isDeepStrictEqual(admission.turnOrchestration, input.turnOrchestration)) {
             throw new RuntimeMessageAuthorityInvariantError('Root Turn admission payload does not match its input');
         }
+        if (admission.execution.kind === 'goal' && admission.execution.eventWait) {
+            await this.resolveExecutionObserver().admitted?.({
+                sessionId: admission.sessionId,
+                turnId: admission.turnId,
+                runId: admission.runId,
+                descriptor: admission.execution,
+            });
+        }
         const session = await this.stores.sessionStore.readHeaderSnapshot(input.sessionId);
         const unavailableReason = admission.execution.kind === 'safe_boundary_continuation'
             ? (this.featureUnavailableReason?.(session) ??

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

@@ -221,6 +221,73 @@ export class HostSessionCatalogCoordinator {
         if (!outcome.ok)
             throw new Error(outcome.error.message);
     }
+    /** Keep the hidden Bot on its owner's selected model without replacing its history. */
+    async synchronizeAssistantBotModel(ownerId, workerId) {
+        return this.#admission.runMany([ownerId, workerId], async (lease) => {
+            const [owner, worker] = await Promise.all([
+                this.#stores.readHeaderRecordSnapshot(ownerId),
+                this.#stores.readHeaderRecordSnapshot(workerId),
+            ]);
+            // A wake may observe a still-running worker. Leave that execution and its
+            // pending interactions intact and require preparation again before admission.
+            if (this.#manager.runningTurnIds(workerId).length ||
+                this.#isTurnBusy?.(workerId) ||
+                worker.header.status === 'running' ||
+                worker.header.status === 'waiting_for_user')
+                return 'deferred';
+            if (!owner.header.executorId &&
+                !worker.header.executorId &&
+                owner.header.llmConnectionId === worker.header.llmConnectionId &&
+                owner.header.llmConnectionSlug === worker.header.llmConnectionSlug &&
+                owner.header.model === worker.header.model &&
+                owner.header.thinkingLevel === worker.header.thinkingLevel)
+                return 'ready';
+            if (owner.header.executorId) {
+                if (owner.header.executorId === worker.header.executorId &&
+                    owner.header.model === worker.header.model &&
+                    owner.header.executorConfig?.model === worker.header.executorConfig?.model &&
+                    owner.header.executorConfig?.mode === worker.header.executorConfig?.mode &&
+                    owner.header.thinkingLevel === worker.header.thinkingLevel)
+                    return 'ready';
+                throw new SessionOperationFailure('operation_unavailable', 'Assistant Bot cannot synchronize the selected external agent');
+            }
+            let connectionId = owner.header.llmConnectionId;
+            if (connectionId === undefined) {
+                // Older headers identify their selected connection by slug alone. Do
+                // not substitute the Host default for that explicit user selection.
+                const selected = await this.#runtimePolicy.operations.resolveExecutionConnection({
+                    kind: 'catalog_slug',
+                    connectionSlug: owner.header.llmConnectionSlug,
+                });
+                if (selected.kind !== 'ready')
+                    throw new SessionOperationFailure('operation_unavailable', 'Assistant model connection is unavailable');
+                connectionId = selected.connection.connectionId;
+            }
+            const outcome = await this.#updateConfiguration({
+                sessionId: workerId,
+                expectedRevision: worker.revision,
+                patch: {
+                    modelTarget: {
+                        kind: 'explicit',
+                        connectionId,
+                        connectionSlug: owner.header.llmConnectionSlug,
+                        model: owner.header.model,
+                    },
+                    thinkingLevel: owner.header.thinkingLevel ?? null,
+                },
+            }, 'ordinary', lease);
+            if (!outcome.ok) {
+                // Execution claims can race the idle observation. The transition
+                // authority refuses them without disposing a live backend.
+                if (outcome.error.code === 'session_busy')
+                    return 'deferred';
+                throw new Error(outcome.error.message);
+            }
+            if (outcome.result.kind !== 'committed')
+                throw new SessionOperationFailure('operation_conflict', 'Assistant Bot configuration changed during model synchronization');
+            return 'ready';
+        });
+    }
     /** WorkHub Action Gate path; callers cannot bypass the typed operation outcome. */
     createForWorkHub(input) {
         return this.#create(input);
@@ -493,11 +560,11 @@ export class HostSessionCatalogCoordinator {
             },
         }, 'workhub');
     }
-    async #updateConfiguration(input, authority = 'ordinary') {
+    async #updateConfiguration(input, authority = 'ordinary', admittedLease) {
         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) => {
+        const update = async (lease) => {
             let commitAttempted = false;
             let confirmedExecutor;
             try {
@@ -587,7 +654,10 @@ export class HostSessionCatalogCoordinator {
                 }
                 return this.#configurationMutationFailure(input, error, 'Session configuration update outcome is unknown');
             }
-        });
+        };
+        return admittedLease
+            ? this.#admission.runAdmitted(input.sessionId, admittedLease, () => update(admittedLease))
+            : this.#admission.run(input.sessionId, update);
     }
     async #reconcileExecutorAfterFailedCommit(previous) {
         try {

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

@@ -0,0 +1,257 @@
+/*
+ * 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 { isWorkHubCoordinationSessionId, userFacingText, } from '@maka/core/session';
+import { SIDE_CONVERSATION_SESSION_LABEL } from '@maka/core/side-conversation';
+import { buildCheckinPrompt, CHECKIN_LOOKBACK_MS, decodeCheckinModelOutput, selectCheckinCandidates, validateCheckinCards, } from '@maka/runtime/session-checkin';
+import { abortable } from '../client/wait-for-ready.js';
+/** Sessions read in full per check-in; the rest of the catalog is judged by its row. */
+const CHECKIN_DEEP_READ_MAX = 24;
+const CHECKIN_TIMEOUT_MS = 60_000;
+const CHECKIN_EFFECTS_RETAINED = 16;
+const EXCLUDED_LABELS = new Set([
+    SIDE_CONVERSATION_SESSION_LABEL,
+    'mode:bot',
+    'mode:deep_research',
+    'scheduled-task',
+]);
+/**
+ * Runs one check-in per effect identity: a retry with the same identity gets
+ * the same answer and never pays for a second model call while this Host runs.
+ */
+export class HostSessionCheckinCoordinator {
+    ports;
+    handlers = {
+        'session.checkin.generate': (input, context) => this.generate(input, context),
+    };
+    #effects = new Map();
+    #aborts = new Set();
+    #closed = false;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    generate(input, context) {
+        if (this.#closed)
+            return Promise.resolve(draining());
+        const existing = this.#effects.get(input.effectId);
+        if (existing) {
+            return existing.since === input.since
+                ? existing.task
+                : Promise.resolve({
+                    ok: false,
+                    error: {
+                        code: 'operation_conflict',
+                        message: 'Check-in effect identity is already in use',
+                    },
+                });
+        }
+        const residency = context.acquireResidency();
+        const abort = new AbortController();
+        this.#aborts.add(abort);
+        const signal = AbortSignal.any([
+            abort.signal,
+            AbortSignal.timeout(this.ports.timeoutMs ?? CHECKIN_TIMEOUT_MS),
+        ]);
+        const task = this.#run(input, context, signal)
+            .then((result) => ({ ok: true, result }), () => this.#closed
+            ? draining()
+            : { ok: false, error: { code: 'internal_failure', message: 'Check-in failed' } })
+            .finally(() => {
+            this.#aborts.delete(abort);
+            residency.release();
+        });
+        this.#effects.set(input.effectId, { since: input.since, task });
+        while (this.#effects.size > CHECKIN_EFFECTS_RETAINED) {
+            this.#effects.delete(this.#effects.keys().next().value);
+        }
+        return task;
+    }
+    beginDrain() {
+        this.#closed = true;
+        for (const abort of this.#aborts)
+            abort.abort();
+    }
+    async close() {
+        this.beginDrain();
+        await Promise.allSettled([...this.#effects.values()].map((effect) => effect.task));
+    }
+    async #run(input, context, signal) {
+        const effectId = input.effectId;
+        if (!(await abortable(() => this.ports.allowed(), signal)))
+            return { kind: 'empty', effectId };
+        const target = await abortable(() => this.ports.readModelTarget(), signal);
+        if (!target)
+            return { kind: 'failed', effectId, errorClass: 'configuration' };
+        const now = this.ports.now?.() ?? Date.now();
+        const sessions = await abortable(() => this.ports.listSessions(context), signal);
+        const recent = sessions
+            .filter((session) => checkinMayRead(session, now))
+            .sort((a, b) => b.activityAt - a.activityAt)
+            .slice(0, CHECKIN_DEEP_READ_MAX);
+        const states = [];
+        let unreadable = 0;
+        for (const session of recent) {
+            const state = await abortable(() => this.ports.readSession(session), signal).catch((error) => {
+                if (signal.aborted)
+                    throw error;
+                unreadable += 1;
+                return undefined;
+            });
+            if (state)
+                states.push(state);
+        }
+        // One unreadable Session is skipped; reading none at all is a broken check-in, not a quiet one.
+        if (unreadable > 0 && states.length === 0) {
+            return { kind: 'failed', effectId, errorClass: 'unknown' };
+        }
+        const candidates = selectCheckinCandidates(states, { now, since: input.since });
+        if (candidates.length === 0)
+            return { kind: 'empty', effectId };
+        const model = await this.ports.generate({
+            target,
+            prompt: buildCheckinPrompt(candidates),
+            abortSignal: signal,
+        });
+        if (!model.ok)
+            return { kind: 'failed', effectId, errorClass: model.errorClass };
+        const decoded = decodeCheckinModelOutput(model.text);
+        if (!decoded.ok)
+            return { kind: 'failed', effectId, errorClass: 'invalid_response' };
+        const validation = validateCheckinCards(decoded.cards, candidates);
+        return {
+            kind: 'generated',
+            effectId,
+            cards: validation.cards,
+            dropped: validation.dropped.length,
+        };
+    }
+}
+const CATALOG_PAGES_MAX = 10;
+const MESSAGES_KEPT = 20;
+/** Reads catalog pages until they run out or the page budget does. */
+export async function listCheckinCatalogSessions(query) {
+    const sessions = [];
+    let next = { kind: 'list_start' };
+    for (let page = 0; page < CATALOG_PAGES_MAX; page += 1) {
+        const outcome = await query(next);
+        if (!outcome.ok || outcome.result.kind !== 'page')
+            break;
+        for (const item of outcome.result.sessions) {
+            if (!('kind' in item))
+                sessions.push(item);
+        }
+        if (!outcome.result.nextCursor)
+            break;
+        next = {
+            kind: 'list_continue',
+            revision: outcome.result.revision,
+            cursor: outcome.result.nextCursor,
+        };
+    }
+    return sessions;
+}
+/** Maps what the Host recorded about one Session into the check-in's view of it. */
+export function checkinSessionState(input) {
+    const turn = input.canonical.rootTurn;
+    const waitingForUser = input.session.status === 'waiting_for_user' ||
+        input.canonical.interactions.pending.length > 0 ||
+        turn?.status === 'waiting_for_user';
+    let lastTurn = null;
+    if (!turn && !waitingForUser)
+        lastTurn = recordedLastTurn(input.turns);
+    if (turn && !waitingForUser) {
+        if (turn.status === 'completed')
+            lastTurn = { status: 'completed' };
+        else if (turn.status === 'failed') {
+            lastTurn = {
+                status: 'failed',
+                failureClass: turn.failureClass,
+                ...(turn.failureMessage ? { failureMessage: turn.failureMessage } : {}),
+            };
+        }
+        else if (turn.status === 'cancelled') {
+            lastTurn = { status: 'cancelled', abortSource: turn.abortSource };
+        }
+        else
+            lastTurn = { status: 'in_progress' };
+    }
+    const goal = input.canonical.goal;
+    const texts = [];
+    for (const message of input.messages) {
+        if (message.type === 'user' && !message.origin && typeof message.text === 'string') {
+            texts.push({ role: 'user', text: userFacingText(message) });
+        }
+        else if (message.type === 'assistant' && typeof message.text === 'string') {
+            texts.push({ role: 'assistant', text: message.text });
+        }
+    }
+    const first = texts.find((message) => message.role === 'user');
+    const recent = texts.slice(-MESSAGES_KEPT);
+    return {
+        sessionId: input.session.id,
+        revision: input.session.revision,
+        name: input.session.name,
+        activityAt: input.session.activityAt,
+        lastTurn,
+        waitingForUser,
+        goal: goal
+            ? { status: goal.status, condition: goal.condition, lastReason: goal.lastReason }
+            : null,
+        todos: input.todos,
+        messages: first && !recent.includes(first) ? [first, ...recent] : recent,
+    };
+}
+/**
+ * A Session written before Root Turn admissions, or imported, still carries
+ * `turn_state` records. Only a recorded status counts; an inferred one is a
+ * reading of old data, not evidence.
+ */
+function recordedLastTurn(turns) {
+    const turn = turns.at(-1);
+    if (!turn || turn.statusSource !== 'recorded')
+        return null;
+    switch (turn.status) {
+        case 'completed':
+            return { status: 'completed' };
+        case 'failed':
+            return {
+                status: 'failed',
+                failureClass: turn.errorClass ?? 'unknown',
+                ...(turn.failureMessage ? { failureMessage: turn.failureMessage } : {}),
+            };
+        case 'aborted':
+            return { status: 'cancelled', abortSource: turn.abortSource ?? 'unknown' };
+        case 'running':
+            return { status: 'in_progress' };
+    }
+}
+/** Judged from the catalog row alone, before any Session is read in full. */
+export function checkinMayRead(session, now) {
+    return (!session.isArchived &&
+        !session.subagent &&
+        !session.parentSessionId &&
+        session.backend === 'ai-sdk' &&
+        session.status !== 'running' &&
+        !(session.liveRunState?.runningTurnIds.length ?? 0) &&
+        !isWorkHubCoordinationSessionId(session.id) &&
+        !session.labels.some((label) => EXCLUDED_LABELS.has(label)) &&
+        session.activityAt >= now - CHECKIN_LOOKBACK_MS);
+}
+function draining() {
+    return { ok: false, error: { code: 'host_draining', message: 'Runtime Host is draining' } };
+}