maka-agent 0.2.0-dev.26.20260909 → 0.2.0-dev.27.20260910

package/node_modules/@maka/runtime/dist/plugin-system-prompt-service.js

@@ -0,0 +1,346 @@
+/*
+ * 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 { createHash } from 'node:crypto';
+import { Service } from './plugin-kernel.js';
+import { MakaPluginRuntimeError, pluginIdentity, registerPluginContribution, } from './plugin-runtime.js';
+import { PluginScopeRegistry } from './plugin-scope-registry.js';
+const PROMPT_NAME_PATTERN = /^[a-z][a-z0-9]*(?:[._:/-][a-z0-9]+)*$/u;
+const VARIABLE_NAME_PATTERN = /^[a-z][a-z0-9_]*$/u;
+const VARIABLE_REFERENCE_PATTERN = /\{\{([^{}]*)\}\}/gu;
+const HOST_BASE_SECTION = 'maka:base';
+export const PLUGIN_SYSTEM_PROMPT_SOURCE_ID = 'plugin.system-prompt';
+/**
+ * Context-scoped, Fiber-owned System Prompt registry for trusted Host plugins.
+ *
+ * Profile contributions are inherited by Session roots. A Session contribution
+ * with the same name shadows its Profile counterpart before either provider is
+ * evaluated. Every assembly snapshots membership and resolves providers anew,
+ * so changes committed by one tool call appear at the next logical model step.
+ */
+export class PluginSystemPromptService extends Service {
+    sections = new PluginScopeRegistry();
+    contexts = new PluginScopeRegistry();
+    variables = new PluginScopeRegistry();
+    constructor(ctx) {
+        super(ctx, 'systemPrompt');
+    }
+    section(definition) {
+        const identity = pluginIdentity(this.ctx);
+        assertHostPromptScope(identity.scopeId);
+        validateSection(definition);
+        return registerPluginContribution(this.ctx, `systemPrompt.section(${JSON.stringify(definition.name)})`, () => this.publishSection(identity, definition));
+    }
+    context(definition) {
+        const identity = pluginIdentity(this.ctx);
+        assertHostPromptScope(identity.scopeId);
+        validateContext(definition);
+        return registerPluginContribution(this.ctx, `systemPrompt.context(${JSON.stringify(definition.name)})`, () => this.publishContext(identity, definition));
+    }
+    variable(name, provider) {
+        const identity = pluginIdentity(this.ctx);
+        assertHostPromptScope(identity.scopeId);
+        validateVariable(name, provider);
+        return registerPluginContribution(this.ctx, `systemPrompt.variable(${JSON.stringify(name)})`, () => this.publishVariable(identity, name, provider));
+    }
+    async assemble(context, baseText) {
+        validateAssemblyContext(context);
+        const visibleSections = this.sections.visible(context.sessionId);
+        const visibleContexts = this.contexts.visible(context.sessionId);
+        const visibleVariables = this.variables.visible(context.sessionId);
+        const sectionSnapshot = [...visibleSections.values()];
+        const contextSnapshot = [...visibleContexts.values()];
+        const variableSnapshot = [...visibleVariables.values()];
+        if (sectionSnapshot.length === 0 &&
+            contextSnapshot.length === 0 &&
+            variableSnapshot.length === 0) {
+            return Object.freeze({ text: baseText, contexts: Object.freeze([]) });
+        }
+        const variables = {};
+        for (const variable of variableSnapshot.sort(compareRegistration)) {
+            const value = await variable.provider(context);
+            if (value !== undefined && typeof value !== 'string') {
+                throw new MakaPluginRuntimeError('activation_failed', `System Prompt variable ${JSON.stringify(variable.name)} returned a non-string value`);
+            }
+            variables[variable.name] = value;
+        }
+        const resolved = [];
+        for (const section of sectionSnapshot) {
+            const value = typeof section.definition.text === 'string'
+                ? section.definition.text
+                : await section.definition.text(context);
+            if (value !== undefined && typeof value !== 'string') {
+                throw new MakaPluginRuntimeError('activation_failed', `System Prompt section ${JSON.stringify(section.definition.name)} returned a non-string value`);
+            }
+            resolved.push({
+                ...section,
+                name: section.definition.name,
+                order: section.definition.order,
+                text: value ?? '',
+                complete: section.definition.complete === true,
+            });
+        }
+        const resolvedContexts = [];
+        for (const entry of contextSnapshot) {
+            const value = typeof entry.definition.text === 'string'
+                ? entry.definition.text
+                : await entry.definition.text(context);
+            if (value !== undefined && typeof value !== 'string') {
+                throw new MakaPluginRuntimeError('activation_failed', `System Prompt context ${JSON.stringify(entry.definition.name)} returned a non-string value`);
+            }
+            if (!value)
+                continue;
+            resolvedContexts.push({
+                ...entry,
+                name: entry.definition.name,
+                order: entry.definition.order,
+                text: interpolate(entry.definition.name, value, variables),
+            });
+        }
+        const complete = resolved.filter((section) => section.complete);
+        if (complete.length > 1) {
+            throw new MakaPluginRuntimeError('activation_failed', `Multiple complete System Prompt sections are active: ${complete
+                .map(({ name }) => JSON.stringify(name))
+                .sort()
+                .join(', ')}`);
+        }
+        const effective = complete.length
+            ? complete
+            : [
+                ...(baseText === undefined
+                    ? []
+                    : [
+                        {
+                            entryId: HOST_BASE_SECTION,
+                            scopeId: 'profile',
+                            extensionId: 'maka',
+                            generation: 0,
+                            name: HOST_BASE_SECTION,
+                            order: 0,
+                            text: baseText,
+                            complete: false,
+                        },
+                    ]),
+                ...resolved,
+            ];
+        const rendered = effective
+            .sort(compareSections)
+            .map((section) => interpolate(section.name, section.text, variables))
+            .filter(Boolean)
+            .join('\n\n');
+        const contexts = Object.freeze(resolvedContexts.sort(compareContexts).map(({ name, text }) => Object.freeze({ name, text })));
+        const revision = promptRevision(resolved, resolvedContexts, variableSnapshot, variables);
+        return Object.freeze({
+            text: rendered || undefined,
+            contexts,
+            sourceRevision: Object.freeze({
+                id: PLUGIN_SYSTEM_PROMPT_SOURCE_ID,
+                revision,
+            }),
+        });
+    }
+    inspect(rootId) {
+        return Object.freeze([
+            ...this.sections.entries(rootId).map((entry) => ({
+                entryId: entry.entryId,
+                scopeId: entry.scopeId,
+                extensionId: entry.extensionId,
+                generation: entry.generation,
+                kind: 'section',
+                name: entry.definition.name,
+                order: entry.definition.order,
+                complete: entry.definition.complete === true,
+            })),
+            ...this.contexts.entries(rootId).map((entry) => ({
+                entryId: entry.entryId,
+                scopeId: entry.scopeId,
+                extensionId: entry.extensionId,
+                generation: entry.generation,
+                kind: 'context',
+                name: entry.definition.name,
+                order: entry.definition.order,
+            })),
+            ...this.variables.entries(rootId).map((entry) => ({
+                entryId: entry.entryId,
+                scopeId: entry.scopeId,
+                extensionId: entry.extensionId,
+                generation: entry.generation,
+                kind: 'variable',
+                name: entry.name,
+            })),
+        ].sort(compareInspection));
+    }
+    publishSection(identity, definition) {
+        const rootId = identity.scopeId;
+        const existing = this.sections.get(rootId, definition.name);
+        assertOwner(existing, identity, 'section', definition.name);
+        const entry = {
+            ...identity,
+            definition: Object.freeze({ ...definition }),
+            token: Symbol(definition.name),
+            retired: false,
+        };
+        return this.sections.publish(rootId, definition.name, entry);
+    }
+    publishVariable(identity, name, provider) {
+        const rootId = identity.scopeId;
+        const existing = this.variables.get(rootId, name);
+        assertOwner(existing, identity, 'variable', name);
+        const entry = {
+            ...identity,
+            name,
+            provider,
+            token: Symbol(name),
+            retired: false,
+        };
+        return this.variables.publish(rootId, name, entry);
+    }
+    publishContext(identity, definition) {
+        const rootId = identity.scopeId;
+        const existing = this.contexts.get(rootId, definition.name);
+        assertOwner(existing, identity, 'context', definition.name);
+        const entry = {
+            ...identity,
+            definition: Object.freeze({ ...definition }),
+            token: Symbol(definition.name),
+            retired: false,
+        };
+        return this.contexts.publish(rootId, definition.name, entry);
+    }
+}
+function assertHostPromptScope(scopeId) {
+    if (scopeId === 'desktop-ui') {
+        throw new MakaPluginRuntimeError('activation_failed', 'desktop-ui plugins cannot contribute Host System Prompt sections');
+    }
+}
+function validateSection(section) {
+    validateName(section.name, 'System Prompt section');
+    if (section.name === HOST_BASE_SECTION) {
+        throw new MakaPluginRuntimeError('activation_failed', 'The Host base System Prompt is reserved');
+    }
+    if (!Number.isFinite(section.order)) {
+        throw new MakaPluginRuntimeError('activation_failed', 'System Prompt section order must be finite');
+    }
+    if (typeof section.text !== 'string' && typeof section.text !== 'function') {
+        throw new MakaPluginRuntimeError('activation_failed', 'System Prompt section text is invalid');
+    }
+}
+function validateContext(context) {
+    validateName(context.name, 'System Prompt context');
+    if (!Number.isFinite(context.order)) {
+        throw new MakaPluginRuntimeError('activation_failed', 'System Prompt context order must be finite');
+    }
+    if (typeof context.text !== 'string' && typeof context.text !== 'function') {
+        throw new MakaPluginRuntimeError('activation_failed', 'System Prompt context text is invalid');
+    }
+}
+function validateVariable(name, provider) {
+    if (!VARIABLE_NAME_PATTERN.test(name) || Buffer.byteLength(name, 'utf8') > 128) {
+        throw new MakaPluginRuntimeError('activation_failed', `Invalid System Prompt variable: ${name}`);
+    }
+    if (typeof provider !== 'function') {
+        throw new MakaPluginRuntimeError('activation_failed', 'System Prompt variable provider is invalid');
+    }
+}
+function validateName(name, label) {
+    if (!PROMPT_NAME_PATTERN.test(name) || Buffer.byteLength(name, 'utf8') > 128) {
+        throw new MakaPluginRuntimeError('activation_failed', `Invalid ${label} name: ${name}`);
+    }
+}
+function validateAssemblyContext(context) {
+    if (!context.sessionId ||
+        !context.turnId ||
+        !context.cwd ||
+        /[\0\r\n]/u.test(context.sessionId) ||
+        /[\0\r\n]/u.test(context.turnId)) {
+        throw new Error('Invalid System Prompt assembly context');
+    }
+}
+function assertOwner(current, identity, kind, name) {
+    if (current && current.entryId !== identity.entryId) {
+        throw new MakaPluginRuntimeError('activation_failed', `System Prompt ${kind} ${JSON.stringify(name)} is already registered by ${current.entryId}`);
+    }
+}
+function interpolate(sectionName, text, variables) {
+    VARIABLE_REFERENCE_PATTERN.lastIndex = 0;
+    return text.replace(VARIABLE_REFERENCE_PATTERN, (reference, rawName) => {
+        if (!VARIABLE_NAME_PATTERN.test(rawName)) {
+            throw new MakaPluginRuntimeError('activation_failed', `Malformed System Prompt variable ${JSON.stringify(reference)} in section ${JSON.stringify(sectionName)}`);
+        }
+        if (!Object.hasOwn(variables, rawName)) {
+            throw new MakaPluginRuntimeError('activation_failed', `Unknown System Prompt variable ${JSON.stringify(rawName)} in section ${JSON.stringify(sectionName)}`);
+        }
+        const value = variables[rawName];
+        if (value === undefined) {
+            throw new MakaPluginRuntimeError('activation_failed', `System Prompt variable ${JSON.stringify(rawName)} has no value in section ${JSON.stringify(sectionName)}`);
+        }
+        return value;
+    });
+}
+function promptRevision(sections, contexts, variables, values) {
+    const canonical = {
+        sections: [...sections].sort(compareSections).map((section) => ({
+            scopeId: section.scopeId,
+            entryId: section.entryId,
+            extensionId: section.extensionId,
+            generation: section.generation,
+            name: section.name,
+            order: section.order,
+            complete: section.complete,
+            text: section.text,
+        })),
+        contexts: [...contexts].sort(compareContexts).map((context) => ({
+            scopeId: context.scopeId,
+            entryId: context.entryId,
+            extensionId: context.extensionId,
+            generation: context.generation,
+            name: context.name,
+            order: context.order,
+            text: context.text,
+        })),
+        variables: [...variables].sort(compareRegistration).map((variable) => ({
+            scopeId: variable.scopeId,
+            entryId: variable.entryId,
+            extensionId: variable.extensionId,
+            generation: variable.generation,
+            name: variable.name,
+            value: values[variable.name] ?? null,
+        })),
+    };
+    return `sha256:${createHash('sha256').update(JSON.stringify(canonical)).digest('hex')}`;
+}
+function compareSections(left, right) {
+    return left.order - right.order || compareCodeUnits(left.name, right.name);
+}
+function compareContexts(left, right) {
+    return left.order - right.order || compareCodeUnits(left.name, right.name);
+}
+function compareRegistration(left, right) {
+    return (compareCodeUnits(left.scopeId, right.scopeId) ||
+        compareCodeUnits(left.entryId, right.entryId) ||
+        left.generation - right.generation);
+}
+function compareInspection(left, right) {
+    return (compareCodeUnits(left.scopeId, right.scopeId) ||
+        compareCodeUnits(left.kind, right.kind) ||
+        compareCodeUnits(left.name, right.name) ||
+        compareCodeUnits(left.entryId, right.entryId));
+}
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/node_modules/@maka/runtime/dist/plugin-tool-service.js

@@ -19,6 +19,7 @@
 import { REQUEST_COMPOSITION_MAX_TOOL_DESCRIPTION_LENGTH } from '@maka/core/run-composition';
 import { Service } from './plugin-kernel.js';
 import { MakaPluginRuntimeError, pluginIdentity, registerPluginContribution, } from './plugin-runtime.js';
+import { PluginScopeRegistry } from './plugin-scope-registry.js';
 import { bindToolActivationIdentity } from './tool-activation-identity.js';
 import { TOOL_SEARCH_NAME, TOOL_SEARCH_PROVIDER_NAME } from './tool-availability.js';
 /**
@@ -30,11 +31,13 @@ import { TOOL_SEARCH_NAME, TOOL_SEARCH_PROVIDER_NAME } from './tool-availability
  * remain Host-owned and cannot be shadowed.
  */
 export class PluginToolService extends Service {
-    layers = new Map();
+    registry = new PluginScopeRegistry();
     onChanged;
+    agents;
     constructor(ctx, options = {}) {
         super(ctx, 'tools');
         this.onChanged = options.onChanged;
+        this.agents = options.agents;
     }
     register(definition) {
         const identity = pluginIdentity(this.ctx);
@@ -54,14 +57,7 @@ export class PluginToolService extends Service {
     resolveContributions(sessionId, coreTools) {
         if (!sessionId || /[\r\n\0]/u.test(sessionId))
             throw new Error('Invalid Tool Session scope');
-        const visible = new Map();
-        for (const entry of this.layers.get('profile')?.values() ?? []) {
-            visible.set(entry.definition.name, entry);
-        }
-        const sessionRoot = `session:${sessionId}`;
-        for (const entry of this.layers.get(sessionRoot)?.values() ?? []) {
-            visible.set(entry.definition.name, entry);
-        }
+        const visible = this.registry.visible(sessionId);
         const coreNames = new Set(coreTools.map(({ name }) => name));
         for (const name of visible.keys()) {
             if (coreNames.has(name)) {
@@ -74,13 +70,7 @@ export class PluginToolService extends Service {
         });
     }
     inspect(rootId) {
-        const layers = rootId
-            ? [[rootId, this.layers.get(rootId)]]
-            : [...this.layers.entries()];
-        return Object.freeze(layers
-            .flatMap(([, layer]) => [...(layer?.values() ?? [])])
-            .sort(compareRegistration)
-            .map((entry) => Object.freeze({
+        return Object.freeze([...this.registry.entries(rootId)].sort(compareRegistration).map((entry) => Object.freeze({
             entryId: entry.entryId,
             scopeId: entry.scopeId,
             extensionId: entry.extensionId,
@@ -92,12 +82,7 @@ export class PluginToolService extends Service {
     }
     publish(identity, definition) {
         const rootId = identity.scopeId;
-        let layer = this.layers.get(rootId);
-        if (!layer) {
-            layer = new Map();
-            this.layers.set(rootId, layer);
-        }
-        const existing = layer.get(definition.name);
+        const existing = this.registry.get(rootId, definition.name);
         if (existing && existing.entryId !== identity.entryId) {
             throw new MakaPluginRuntimeError('activation_failed', `Plugin Tool ${JSON.stringify(definition.name)} is already registered by ${existing.entryId}`);
         }
@@ -110,7 +95,9 @@ export class PluginToolService extends Service {
                 }
                 entry.activeCalls += 1;
                 try {
-                    return await definition.impl(args, context);
+                    return await (this.agents
+                        ? this.agents.withInvocation(context, () => definition.impl(args, context))
+                        : definition.impl(args, context));
                 }
                 finally {
                     entry.activeCalls -= 1;
@@ -138,35 +125,14 @@ export class PluginToolService extends Service {
             retired: false,
             drainWaiters: new Set(),
         };
-        layer.set(definition.name, entry);
-        try {
-            this.notifyChanged(rootId);
-        }
-        catch (error) {
-            if (existing)
-                layer.set(definition.name, existing);
-            else
-                layer.delete(definition.name);
-            if (layer.size === 0)
-                this.layers.delete(rootId);
-            throw error;
-        }
-        return async () => {
-            entry.retired = true;
-            const currentLayer = this.layers.get(rootId);
-            if (currentLayer?.get(definition.name)?.token === entry.token) {
-                if (existing && !existing.retired)
-                    currentLayer.set(definition.name, existing);
-                else
-                    currentLayer.delete(definition.name);
-                if (currentLayer.size === 0)
-                    this.layers.delete(rootId);
-                this.notifyChanged(rootId);
-            }
-            if (entry.activeCalls > 0) {
-                await new Promise((resolve) => entry.drainWaiters.add(resolve));
-            }
-        };
+        return this.registry.publish(rootId, definition.name, entry, {
+            onChanged: (changedRootId) => this.notifyChanged(changedRootId),
+            onRetired: async (retired) => {
+                if (retired.activeCalls > 0) {
+                    await new Promise((resolve) => retired.drainWaiters.add(resolve));
+                }
+            },
+        });
     }
     notifyChanged(rootId) {
         this.ctx.emit('tools/change');

package/node_modules/@maka/runtime/dist/plugin-user-question-service.js

@@ -0,0 +1,43 @@
+/*
+ * 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 { Service } from './plugin-kernel.js';
+import { pluginInvocationSignal } from './plugin-invocation-signal.js';
+/** Structured human-input surface bound to the current Agent invocation. */
+export class PluginUserQuestionService extends Service {
+    agents;
+    constructor(ctx, agents) {
+        super(ctx, 'userQuestions');
+        this.agents = agents;
+    }
+    ask(questions) {
+        const ask = this.agents.requireInvocation().toolContext?.askUserQuestion;
+        if (!ask)
+            throw new Error('User questions are unavailable on this Agent surface');
+        return ask([...questions]);
+    }
+    requestForm(form, options = {}) {
+        const invocation = this.agents.requireInvocation();
+        const request = invocation.toolContext?.requestUserForm;
+        if (!request)
+            throw new Error('Structured user forms are unavailable on this Agent surface');
+        return request(form, {
+            cancellationSignal: pluginInvocationSignal(invocation.abortSignal, options.signal),
+        });
+    }
+}

package/node_modules/@maka/runtime/dist/plugin-web-service.js

@@ -0,0 +1,69 @@
+/*
+ * 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 { WEB_SEARCH_DEFAULT_LIMIT, normalizeWebSearchLimit, normalizeWebSearchQuery, } from '@maka/core/web-search';
+import { Service } from './plugin-kernel.js';
+import { pluginInvocationSignal } from './plugin-invocation-signal.js';
+/** Provider-policy-aware web search and fetch surface. */
+export class PluginWebService extends Service {
+    agents;
+    webRuntime;
+    constructor(ctx, agents) {
+        super(ctx, 'web');
+        this.agents = agents;
+    }
+    bindRuntime(runtime) {
+        if (this.ctx.maka)
+            throw new Error('Only the Host may bind the Web Runtime');
+        if (this.webRuntime)
+            throw new Error('Plugin Web Runtime is already bound');
+        this.webRuntime = runtime;
+        return this.ctx.effect(() => () => {
+            if (this.webRuntime === runtime)
+                this.webRuntime = undefined;
+        }, 'web.bindRuntime()');
+    }
+    search(query, options = {}) {
+        const invocation = this.agents.requireInvocation();
+        const normalized = normalizeWebSearchQuery(query);
+        if (!normalized)
+            throw new TypeError('Web search query is invalid');
+        return this.runtime().search({
+            query: normalized,
+            limit: normalizeWebSearchLimit(options.limit ?? WEB_SEARCH_DEFAULT_LIMIT),
+            sessionId: invocation.sessionId,
+            abortSignal: pluginInvocationSignal(invocation.abortSignal, options.signal),
+        });
+    }
+    fetch(url, options = {}) {
+        const invocation = this.agents.requireInvocation();
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            throw new TypeError('Web URL must use HTTP or HTTPS');
+        return this.runtime().fetch({
+            url: parsed.toString(),
+            sessionId: invocation.sessionId,
+            abortSignal: pluginInvocationSignal(invocation.abortSignal, options.signal),
+        });
+    }
+    runtime() {
+        if (!this.webRuntime)
+            throw new Error('Plugin Web Runtime is unavailable');
+        return this.webRuntime;
+    }
+}