@borgee/agents-host 0.2.2 → 0.2.28

package/dist/context/injection.js

@@ -0,0 +1,355 @@
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+const CHANNEL_CONTEXT_ROOT_DIRNAME = 'channel-context';
+const CHANNEL_CONTEXT_PAYLOAD_FILENAME = 'context.json';
+const CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME = '.localhost-gateway-auth.json';
+const TASK_WORKSPACE_ROOT_DIRNAME = '.borgee-task-workspaces';
+export class ChannelContextPreparationError extends Error {
+    partialContext;
+    constructor(message, partialContext, options) {
+        super(message, options);
+        this.partialContext = partialContext;
+        this.name = 'ChannelContextPreparationError';
+    }
+}
+const DEFAULT_FILE_SYSTEM = {
+    async mkdir(path, options) {
+        await fs.mkdir(path, options);
+    },
+    async readdir(path) {
+        return await fs.readdir(path);
+    },
+    async readFile(path, options) {
+        return await fs.readFile(path, options);
+    },
+    async writeFile(path, data, options) {
+        await fs.writeFile(path, data, options);
+    },
+    async unlink(path) {
+        await fs.unlink(path);
+    },
+    async access(path) {
+        await fs.access(path);
+    },
+};
+const BORGEE_AGENT_SKILL_DIRNAME = 'borgee-agent';
+const TASK_ASSIGNMENT_PREAMBLE_PATTERN = /^This is a task assignment \(task_id: (.+)\)\. The work belongs to this thread\b/u;
+function toSkillRuntimePayload(skillRuntime) {
+    if (!skillRuntime) {
+        return undefined;
+    }
+    return {
+        skillDirectoryPath: skillRuntime.skillDirectoryPath,
+        nodeCliPath: skillRuntime.nodeCliPath,
+        pythonCliPath: skillRuntime.pythonCliPath,
+    };
+}
+function buildLocalhostGatewayAuthPayload(channelId, localhostGateway) {
+    if (!localhostGateway) {
+        return undefined;
+    }
+    return {
+        schemaVersion: 1,
+        channelId,
+        localhostGateway: {
+            token: localhostGateway.token,
+        },
+    };
+}
+function buildChannelContextPayload(channelId, collaborationOutcome, attentionSnapshot, taskThreadCollaborationContract, collaborationCapabilities, missedCollaborationDiagnostic, skillRuntime, localhostGateway, options) {
+    return {
+        schemaVersion: 1,
+        channelId,
+        ...(collaborationOutcome ? { collaborationOutcome } : {}),
+        ...(attentionSnapshot ? { attentionSnapshot } : {}),
+        ...(taskThreadCollaborationContract ? { taskThreadCollaborationContract } : {}),
+        ...(collaborationCapabilities ? { collaborationCapabilities } : {}),
+        ...(missedCollaborationDiagnostic ? { missedCollaborationDiagnostic } : {}),
+        ...(skillRuntime ? { skillRuntime: toSkillRuntimePayload(skillRuntime) } : {}),
+        ...(localhostGateway ? { localhostGateway } : {}),
+        ...(options?.taskAssignmentContext ? { taskAssignmentContext: options.taskAssignmentContext } : {}),
+        ...(options?.taskWorkspace ? { taskWorkspace: options.taskWorkspace } : {}),
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function canRoundTripThroughUriComponentEncoding(value) {
+    try {
+        return decodeURIComponent(encodeURIComponent(value)) === value;
+    }
+    catch (error) {
+        if (error instanceof URIError) {
+            return false;
+        }
+        throw error;
+    }
+}
+function isUsableTaskId(value) {
+    return value.length > 0
+        && !/[\u0000-\u001f\u007f\s]/u.test(value)
+        && canRoundTripThroughUriComponentEncoding(value);
+}
+function sanitizeTaskAssignmentContext(value) {
+    if (!isRecord(value) || value.active !== true) {
+        return undefined;
+    }
+    const currentTaskId = typeof value.currentTaskId === 'string'
+        ? value.currentTaskId.trim()
+        : '';
+    return currentTaskId && isUsableTaskId(currentTaskId)
+        ? { active: true, currentTaskId }
+        : { active: true };
+}
+export function extractTaskIdFromTaskAssignmentContent(incomingContent) {
+    if (typeof incomingContent !== 'string') {
+        return undefined;
+    }
+    const currentTaskId = incomingContent.match(TASK_ASSIGNMENT_PREAMBLE_PATTERN)?.[1]?.trim();
+    return currentTaskId && isUsableTaskId(currentTaskId)
+        ? currentTaskId
+        : undefined;
+}
+function buildTaskAssignmentContextForTurn(options, existingContext) {
+    if (options?.incomingMessageType === 'task_assignment') {
+        const currentTaskId = extractTaskIdFromTaskAssignmentContent(options.incomingContent);
+        return currentTaskId ? { active: true, currentTaskId } : { active: true };
+    }
+    return existingContext;
+}
+async function readExistingTaskAssignmentContext(payloadPath, fileSystem) {
+    try {
+        const raw = await fileSystem.readFile(payloadPath, { encoding: 'utf8' });
+        const payload = JSON.parse(raw);
+        return sanitizeTaskAssignmentContext(payload.taskAssignmentContext);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function encodeChannelPathSegment(channelId) {
+    const encoded = Buffer.from(channelId, 'utf8').toString('hex');
+    return encoded.length > 0 ? encoded : 'empty';
+}
+export function resolveChannelContextDirectory(stateRootDir, channelId) {
+    return resolve(stateRootDir, CHANNEL_CONTEXT_ROOT_DIRNAME, encodeChannelPathSegment(channelId));
+}
+export function resolveChannelContextPayloadPath(stateRootDir, channelId) {
+    return join(resolveChannelContextDirectory(stateRootDir, channelId), CHANNEL_CONTEXT_PAYLOAD_FILENAME);
+}
+export function resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir) {
+    return join(resolve(startupWorkspaceRootDir), TASK_WORKSPACE_ROOT_DIRNAME);
+}
+export function resolveTaskWorkspaceDirectory(startupWorkspaceRootDir, channelId, taskId) {
+    return join(resolveTaskWorkspaceRootDirectory(startupWorkspaceRootDir), encodeChannelPathSegment(channelId), encodeChannelPathSegment(taskId));
+}
+export function resolveChannelContextGatewayAuthPath(stateRootDir, channelId, turnExecutionId) {
+    const filename = turnExecutionId
+        ? `.localhost-gateway-auth.${Buffer.from(turnExecutionId, 'utf8').toString('hex')}.json`
+        : CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME;
+    return join(resolveChannelContextDirectory(stateRootDir, channelId), filename);
+}
+export function resolveGatewayAuthPathFromPayloadPath(payloadPath) {
+    return join(dirname(payloadPath), CHANNEL_CONTEXT_GATEWAY_AUTH_FILENAME);
+}
+const LEGACY_TURN_SCOPED_GATEWAY_AUTH_BASENAME_PREFIX = '.localhost-gateway-auth.';
+async function pruneLegacyGatewayAuthSidecars(fileSystem, directoryPath) {
+    let entries;
+    try {
+        entries = await fileSystem.readdir(directoryPath);
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error && 'code' in error ? error.code : undefined;
+        if (code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    await Promise.all(entries
+        .filter((entry) => entry.startsWith(LEGACY_TURN_SCOPED_GATEWAY_AUTH_BASENAME_PREFIX)
+        && entry.endsWith('.json'))
+        .map(async (entry) => {
+        await fileSystem.unlink(join(directoryPath, entry)).catch((error) => {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        });
+    }));
+}
+async function resolvePackageRootFromModuleUrl(moduleUrl, fileSystem = DEFAULT_FILE_SYSTEM) {
+    let currentPath = dirname(fileURLToPath(moduleUrl));
+    for (;;) {
+        try {
+            await fileSystem.access(join(currentPath, 'package.json'));
+            return currentPath;
+        }
+        catch { }
+        const parentPath = resolve(currentPath, '..');
+        if (parentPath === currentPath) {
+            throw new Error(`Unable to resolve agents-host package root from ${moduleUrl}`);
+        }
+        currentPath = parentPath;
+    }
+}
+export async function resolveBorgeeAgentSkillRuntimeAssets(moduleUrl, fileSystem = DEFAULT_FILE_SYSTEM) {
+    const packageRootPath = await resolvePackageRootFromModuleUrl(moduleUrl, fileSystem);
+    const skillDirectoryPath = join(packageRootPath, 'skills', BORGEE_AGENT_SKILL_DIRNAME);
+    const skillMarkdownPath = join(skillDirectoryPath, 'SKILL.md');
+    const nodeCliPath = join(skillDirectoryPath, 'borgee-agent.mjs');
+    const pythonCliPath = join(skillDirectoryPath, 'borgee-agent.py');
+    await Promise.all([
+        fileSystem.access(skillDirectoryPath),
+        fileSystem.access(skillMarkdownPath),
+        fileSystem.access(nodeCliPath),
+        fileSystem.access(pythonCliPath),
+    ]);
+    return {
+        skillDirectoryPath,
+        skillMarkdownPath,
+        nodeCliPath,
+        pythonCliPath,
+    };
+}
+class PackageSkillAssetResolver {
+    moduleUrl;
+    fileSystem;
+    resolutionPromise = null;
+    constructor(moduleUrl, fileSystem = DEFAULT_FILE_SYSTEM) {
+        this.moduleUrl = moduleUrl;
+        this.fileSystem = fileSystem;
+    }
+    resolve() {
+        this.resolutionPromise ??= resolveBorgeeAgentSkillRuntimeAssets(this.moduleUrl, this.fileSystem);
+        return this.resolutionPromise;
+    }
+}
+export class FileChannelContextStore {
+    stateRootDir;
+    fileSystem;
+    skillRuntimeEnabled;
+    skillAssetResolver;
+    localhostGateway;
+    startupWorkspaceRootDir;
+    constructor(stateRootDir, options = {}) {
+        this.stateRootDir = stateRootDir;
+        this.fileSystem = options.fileSystem ?? DEFAULT_FILE_SYSTEM;
+        this.skillRuntimeEnabled = options.skillRuntimeEnabled ?? false;
+        this.skillAssetResolver = options.skillAssetResolver ?? new PackageSkillAssetResolver(import.meta.url, this.fileSystem);
+        this.localhostGateway = options.localhostGateway;
+        this.startupWorkspaceRootDir = resolve(options.taskWorkspaceRootDir ?? process.cwd());
+    }
+    async prepare(inputOrChannelId, options) {
+        const input = typeof inputOrChannelId === 'string'
+            ? { channelId: inputOrChannelId, ...options }
+            : inputOrChannelId;
+        const turnMode = input.collaboration?.turnMode ?? 'ordinary';
+        const collaborationCommandsEnabled = input.collaboration?.enabled === true && input.collaboration.sendRoutesAllowed === true;
+        const collaborationRoutesAllowedForTurnMode = turnMode === 'ordinary';
+        const auxiliaryCollaborationEnabled = collaborationCommandsEnabled && collaborationRoutesAllowedForTurnMode;
+        const directoryPath = resolveChannelContextDirectory(this.stateRootDir, input.channelId);
+        const payloadPath = resolveChannelContextPayloadPath(this.stateRootDir, input.channelId);
+        const gatewayAuthPath = resolveGatewayAuthPathFromPayloadPath(payloadPath);
+        const existingTaskAssignmentContext = await readExistingTaskAssignmentContext(payloadPath, this.fileSystem);
+        const skillRuntime = this.skillRuntimeEnabled
+            ? await this.resolveSkillRuntimeBestEffort()
+            : undefined;
+        const issuedLocalhostGateway = skillRuntime
+            ? this.localhostGateway?.resolveBootstrap(input.channelId, {
+                collaboration: auxiliaryCollaborationEnabled && input.collaboration?.turnExecutionId
+                    ? {
+                        enabled: true,
+                        turnExecutionId: input.collaboration.turnExecutionId,
+                    }
+                    : undefined,
+            })
+            : undefined;
+        const localhostGateway = issuedLocalhostGateway
+            ? {
+                baseUrl: issuedLocalhostGateway.baseUrl,
+                ...(auxiliaryCollaborationEnabled
+                    ? {
+                        collaboration: {
+                            enabled: true,
+                        },
+                    }
+                    : {}),
+            }
+            : undefined;
+        const taskAssignmentContext = buildTaskAssignmentContextForTurn({
+            incomingMessageType: input.incomingMessageType,
+            incomingContent: input.incomingContent,
+        }, existingTaskAssignmentContext);
+        const taskWorkspace = taskAssignmentContext?.currentTaskId
+            ? {
+                currentTaskId: taskAssignmentContext.currentTaskId,
+                rootPath: resolveTaskWorkspaceDirectory(this.startupWorkspaceRootDir, input.channelId, taskAssignmentContext.currentTaskId),
+            }
+            : undefined;
+        const payload = buildChannelContextPayload(input.channelId, input.collaborationOutcome, input.attentionSnapshot, input.taskThreadCollaborationContract, input.collaborationCapabilities, input.missedCollaborationDiagnostic, skillRuntime, localhostGateway, taskAssignmentContext || taskWorkspace
+            ? {
+                ...(taskAssignmentContext ? { taskAssignmentContext } : {}),
+                ...(taskWorkspace ? { taskWorkspace } : {}),
+            }
+            : undefined);
+        const gatewayAuthPayload = buildLocalhostGatewayAuthPayload(input.channelId, issuedLocalhostGateway);
+        let taskWorkspaceMaterialized = false;
+        let payloadWritten = false;
+        let gatewayAuthWritten = false;
+        const preparedContext = {
+            directoryPath,
+            payload,
+            payloadPath,
+            gatewayAuthPath: gatewayAuthPayload ? gatewayAuthPath : undefined,
+            skillRuntime,
+            localhostGateway,
+            taskWorkspace,
+        };
+        try {
+            await this.fileSystem.mkdir(directoryPath, { recursive: true, mode: 0o700 });
+            if (taskWorkspace) {
+                await this.fileSystem.mkdir(taskWorkspace.rootPath, { recursive: true, mode: 0o700 });
+                taskWorkspaceMaterialized = true;
+            }
+            await pruneLegacyGatewayAuthSidecars(this.fileSystem, directoryPath);
+            await this.fileSystem.writeFile(payloadPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+            payloadWritten = true;
+            if (gatewayAuthPayload) {
+                await this.fileSystem.writeFile(gatewayAuthPath, `${JSON.stringify(gatewayAuthPayload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+                gatewayAuthWritten = true;
+            }
+            else {
+                await this.fileSystem.unlink(gatewayAuthPath).catch((error) => {
+                    if (error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                });
+                this.localhostGateway?.clearChannel(input.channelId);
+            }
+            if (issuedLocalhostGateway) {
+                this.localhostGateway?.publishPayload(input.channelId, payloadPath, payload);
+            }
+            return preparedContext;
+        }
+        catch (error) {
+            const partialContext = {
+                directoryPath,
+                payload,
+                payloadPath: payloadWritten ? payloadPath : undefined,
+                gatewayAuthPath: gatewayAuthWritten ? gatewayAuthPath : undefined,
+                skillRuntime: payloadWritten ? skillRuntime : undefined,
+                localhostGateway: payloadWritten ? localhostGateway : undefined,
+                taskWorkspace: taskWorkspaceMaterialized ? taskWorkspace : undefined,
+            };
+            throw new ChannelContextPreparationError('failed to persist channel context payload', partialContext, { cause: error });
+        }
+    }
+    async resolveSkillRuntimeBestEffort() {
+        try {
+            return await this.skillAssetResolver.resolve();
+        }
+        catch {
+            return undefined;
+        }
+    }
+}

package/dist/context/prompt.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderKind } from '../types.js';
+import type { PreparedPromptContext, ProviderKind } from '../types.js';
 /**
  * Builds the per-turn prompt. Conversation memory is intentionally NOT
  * assembled here: each provider's CLI client resumes a native per-channel
@@ -12,4 +12,7 @@ export declare function buildPrompt(params: {
     channelId: string;
     incomingAuthorId: string;
     incomingContent: string;
+    incomingEventKind?: string;
+    incomingMessageType?: string;
+    promptContext?: PreparedPromptContext;
 }): string;

package/dist/context/prompt.js

@@ -1,5 +1,210 @@
+import { AWAITING_USER_CONTROL_PREFIX } from '../providers/awaiting-user.js';
+import { buildAttentionSummaryLines } from './attention.js';
+import { buildCollaborationCapabilityDeclarationSummaryLines, buildMissedCollaborationDiagnosticSummaryLines, } from './collaboration-capabilities-diagnostics.js';
+import { buildCollaborationOutcomeSummaryLines } from './collaboration-outcome.js';
+import { buildTaskThreadCollaborationSummaryLines } from './task-thread-collaboration.js';
 function providerLabel(provider) {
-    return provider === 'copilot' ? 'GitHub Copilot' : 'Claude';
+    if (provider === 'copilot') {
+        return 'GitHub Copilot';
+    }
+    if (provider === 'codex') {
+        return 'Codex';
+    }
+    return 'Claude';
+}
+function buildSkillRuntimePromptLines(context) {
+    if (!context?.skillRuntime) {
+        return [];
+    }
+    return [
+        '',
+        'Read-only local skill runtime bootstrap is available for this turn.',
+        `Channel context payload: ${context.channelContextPayloadPath}`,
+        `Skill guide: ${context.skillRuntime.skillMarkdownPath}`,
+        `Node CLI: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --print-bootstrap`,
+        `Python CLI: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --print-bootstrap`,
+        'These CLIs are local-only, may only access the loopback gateway described below, must not mutate files or the local environment, and may only send auxiliary collaboration messages when that gateway surface is explicitly advertised below.',
+    ];
+}
+function buildLocalhostGatewayPromptLines(context) {
+    if (!context?.localhostGateway) {
+        return [];
+    }
+    if (!context.gatewayAuthPath) {
+        return [];
+    }
+    const lines = [
+        '',
+        'A loopback-only localhost gateway is available for this turn.',
+        'Use the packaged local CLI with the existing --context payload to access the documented gateway surface.',
+        `Gateway auth sidecar for this turn: ${context.gatewayAuthPath}`,
+    ];
+    const isTaskAssignmentThread = context.taskAssignmentContext?.active === true;
+    if (!context.skillRuntime) {
+        return lines;
+    }
+    lines.push('The read-only gateway commands listed in this prompt are already authorized for this turn and may be executed directly.', 'Do not ask the user for permission before using the read-only gateway commands listed below.', 'If the user asks about channel history, visible participants, or your current agent identity, run the relevant read command first and answer from its result instead of speculating about authorization.', `Node gateway checks: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --health`, `Node channel bootstrap: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-bootstrap`, `Node agent identity: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-me`, `Node channel history: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-history --limit 20`, `Python gateway checks: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --health`, `Python channel bootstrap: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-bootstrap`, `Python agent identity: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-me`, `Python channel history: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --read-history --limit 20`);
+    if (isTaskAssignmentThread) {
+        lines.push('Task-collection commands remain disabled inside this task thread; use the parent channel for create/list task operations.', `Node get current thread task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task`, `Node update current thread task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`, `Python get current thread task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task`, `Python update current thread task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`);
+    }
+    else {
+        lines.push(`Node create task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --create-task --title "<title>" [--description "<description>"] [--assignee-id "<assignee-id>"]`, `Node list tasks: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-tasks`, `Node get task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task --task-id "<task-id>"`, `Node update task: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task --task-id "<task-id>" [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`, `Python create task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --create-task --title "<title>" [--description "<description>"] [--assignee-id "<assignee-id>"]`, `Python list tasks: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-tasks`, `Python get task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --get-task --task-id "<task-id>"`, `Python update task: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --update-task --task-id "<task-id>" [--status "<status>"] [--assignee-id "<assignee-id>"] [--title "<title>"]`);
+    }
+    if (context.localhostGateway.collaboration?.enabled &&
+        (context.collaborationTurnMode ?? 'ordinary') === 'ordinary') {
+        const turnExecutionArgument = context.collaborationTurnExecutionId
+            ? ` --turn-execution-id ${context.collaborationTurnExecutionId}`
+            : '';
+        lines.push('Auxiliary collaboration commands are available for this turn. Use them only for short targeted escalation, mention, or reply notices, never for the main final answer body.', 'When you need the host-private in-flight draft for this live collaboration turn, use the dedicated read-draft command rather than inspecting public channel messages.', 'When --list-users is listed below, it is a read-only command for this turn and may be executed directly without asking for permission.', 'When the user explicitly asks you to mention, ping, notify, or send a short note to another visible participant, use the dedicated send-mention command directly and include a visible <@targetId> token in the body.', 'If the user asks you to @ another agent now, send the short auxiliary mention first, then confirm what you sent.', 'If the user says "the other agent" and only one other visible agent is present, resolve that target from --list-users and then use --send-mention with that participant id.', 'If collaboration with another visible agent would help, use these auxiliary commands to send a short targeted mention or reply-thread note yourself rather than asking AgentsHost to orchestrate a special protocol.', `Node private draft snapshot: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --read-draft`, `Node user directory: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-users`, `Node auxiliary mention: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --send-mention user-id --body "Need review from <@user-id>"`, `Node reply thread notice: node ${context.skillRuntime.nodeCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --send-message --body "Following up here" --reply-to message-id`, `Python private draft snapshot: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --read-draft`, `Python user directory: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath} --list-users`, `Python auxiliary mention: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --send-mention user-id --body "Need review from <@user-id>"`, `Python reply thread notice: python3 ${context.skillRuntime.pythonCliPath} --context ${context.channelContextPayloadPath} --auth-path ${context.gatewayAuthPath}${turnExecutionArgument} --send-message --body "Following up here" --reply-to message-id`);
+    }
+    return lines;
+}
+function buildTaskAssignmentPromptLines(params) {
+    const isTaskAssignmentTurn = params.incomingMessageType?.trim() === 'task_assignment';
+    const taskAssignmentContext = params.promptContext?.taskAssignmentContext;
+    if (!isTaskAssignmentTurn && taskAssignmentContext?.active !== true) {
+        return [];
+    }
+    const lines = isTaskAssignmentTurn
+        ? [
+            'This message is a task assignment.',
+            'The assigned work belongs to this thread. Do the work here.',
+        ]
+        : [
+            'This thread is continuing an existing task assignment.',
+            'Keep the main work in this thread.',
+        ];
+    if (taskAssignmentContext?.currentTaskId) {
+        lines.push(`Current assigned task id: ${taskAssignmentContext.currentTaskId}.`);
+        lines.push('Inside this task thread, the packaged Node and Python CLIs may omit --task-id for --get-task and --update-task because the current task id is already persisted in the injected thread context.');
+        if (params.promptContext?.taskWorkspace) {
+            lines.push(`Task-scoped writable workspace root: ${params.promptContext.taskWorkspace.rootPath}.`);
+            lines.push('This writable workspace is local to agents-host for the current task thread. It does not imply that the target repository has already been checked out there.');
+        }
+    }
+    else if (taskAssignmentContext?.active === true) {
+        lines.push('No current task id is persisted in the injected thread context for this task thread.');
+        lines.push('Inside this task thread, shorthand --get-task/--update-task calls without --task-id use an agents-host local fallback that scans visible parent-channel tasks for this thread; pass --task-id explicitly if that fallback cannot resolve a unique task.');
+    }
+    lines.push('Set the task status to in_progress when you start.', 'When you finish, set the task status to in_review and return your normal final response in this thread.', 'Do not use an auxiliary message command for the main completion report; reserve it for intentional targeted escalation or cross-channel notification.', 'Do not use create/list task operations inside this task thread; those remain parent-channel operations.', 'Do not move the main work back to the parent channel.');
+    return lines;
+}
+function buildInboundMetadataLines(params) {
+    return [
+        `Incoming transport event kind: ${params.incomingEventKind?.trim() || 'message'}`,
+        `Incoming semantic message type: ${params.incomingMessageType?.trim() || 'default'}`,
+        ...(() => {
+            const lines = buildTaskThreadCollaborationSummaryLines(params.promptContext?.taskThreadCollaborationContract);
+            return lines.length > 0 ? ['', ...lines] : [];
+        })(),
+        ...buildTaskAssignmentPromptLines(params),
+    ];
+}
+function describeIdentity(identity) {
+    if (!identity) {
+        return null;
+    }
+    const name = identity.displayName?.trim();
+    const label = name && name.length > 0 ? `${name} (${identity.id})` : identity.id;
+    return `${label}, kind=${identity.kind}`;
+}
+function buildTurnControlPromptLines(context) {
+    const taskThreadAttentionAvailable = context?.taskAssignmentContext?.active === true
+        && typeof context.taskAssignmentContext.currentTaskId === 'string'
+        && context.taskAssignmentContext.currentTaskId.trim().length > 0;
+    const attentionLines = context?.attentionSnapshot
+        ? [
+            'Attention controls are projection-only host hints. They do not bypass server-side mention policy or widen message delivery.',
+            `To follow ordinary delivered human messages in this channel, add "attentionUpdate":"follow-channel".`,
+            `To stop follow-based human wake for this channel, add "attentionUpdate":"unfollow-channel".`,
+            `To mute ordinary delivered human wake while keeping explicit mentions and task assignments untouched, add "attentionUpdate":"mute-channel".`,
+            `To set a durable channel-level attention hint, add "attentionUpdate":"claim-channel".`,
+            ...(taskThreadAttentionAvailable
+                ? [
+                    `To set a durable task-thread attention hint, add "attentionUpdate":"claim-task-thread" only when this turn has active injected task-thread context with a usable currentTaskId.`,
+                    `To clear a local claim without changing deliveryMode, add "attentionUpdate":"unclaim-channel" or "attentionUpdate":"unclaim-task-thread".`,
+                ]
+                : [
+                    `To clear a local channel claim without changing deliveryMode, add "attentionUpdate":"unclaim-channel".`,
+                ]),
+        ]
+        : [];
+    const attentionOnlyLine = context?.attentionSnapshot
+        ? [
+            `For an attention-only reply, keep a non-empty visible body and append: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"attention-only","attentionUpdate":"follow-channel"}`,
+        ]
+        : [];
+    if (!context) {
+        return [
+            `Only when you need host-local turn control, append exactly one final non-empty line starting with ${AWAITING_USER_CONTROL_PREFIX}.`,
+            `For ordinary blocked-on-human turns, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"awaiting-user","question":"<short question>","reason":"<short reason>"}`,
+            ...attentionLines,
+            ...attentionOnlyLine,
+            'Do not emit multiple control lines, and do not use a control footer for ordinary answers.',
+        ];
+    }
+    if (context.collaborationTurnMode === 'protocol-managed' && context.protocol) {
+        const selfIdentity = describeIdentity(context.grounding?.self);
+        const incomingIdentity = describeIdentity(context.grounding?.incomingAuthor);
+        const peerIdentity = describeIdentity(context.grounding?.peer);
+        return [
+            `Protocol-managed collaboration is already active for this turn. Your host-managed role is ${context.protocol.role}, and your target peer is ${context.protocol.targetPeerId}.`,
+            ...(selfIdentity ? [`Your self identity for this turn: ${selfIdentity}.`] : []),
+            ...(peerIdentity ? [`Your peer for this turn: ${peerIdentity}.`] : []),
+            ...(incomingIdentity ? [`The incoming author for this turn is ${incomingIdentity}.`] : []),
+            'The host will deliver the visible protocol reply body for you; you only decide the body plus exactly one control footer.',
+            'Do not use auxiliary collaboration send commands during this turn, even if other turns can use them.',
+            'Do not attempt a localhost gateway message post during this turn.',
+            `When handing off to the named peer, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"continue-to-peer"}`,
+            `When finishing locally, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"conclude-locally"}`,
+            `If you are blocked on the human instead, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"awaiting-user","question":"<short question>","reason":"<short reason>"}`,
+            ...(context.attentionSnapshot
+                ? ['You may add one attentionUpdate field to continue-to-peer, conclude-locally, or awaiting-user when you also need an attention change for this channel.']
+                : []),
+            ...attentionLines,
+            'Do not emit multiple control lines, and do not use start-protocol while host-managed collaboration is already active.',
+        ];
+    }
+    if (context.collaborationTurnMode === 'silent-kickoff' && context.kickoff) {
+        const kickoff = context.kickoff;
+        const otherParticipantId = kickoff.participantIds.find((participantId) => participantId !== kickoff.issuerId);
+        const selfIdentity = describeIdentity(context.grounding?.self);
+        const incomingIdentity = describeIdentity(context.grounding?.incomingAuthor);
+        const peerIdentity = describeIdentity(context.grounding?.peer);
+        const participantSummary = context.grounding?.participants
+            ?.map((participant) => describeIdentity(participant))
+            .filter((participant) => participant != null)
+            .join('; ');
+        return [
+            `Silent protocol kickoff evaluation is active for anchor ${kickoff.anchorMessageId}. The issuer is ${kickoff.issuerId}${otherParticipantId ? ` and the other participant is ${otherParticipantId}` : ''}.`,
+            ...(context.grounding?.hostRecognizedKickoffCandidate
+                ? [
+                    'The host has already recognized this message as a structurally valid kickoff candidate and is asking you to decide whether host-managed collaboration should start.',
+                ]
+                : []),
+            ...(selfIdentity ? [`Your self identity for this decision: ${selfIdentity}.`] : []),
+            ...(peerIdentity ? [`Your peer candidate for this decision: ${peerIdentity}.`] : []),
+            ...(incomingIdentity
+                ? [`The incoming author for this decision is ${incomingIdentity}.`]
+                : []),
+            ...(participantSummary ? [`Visible kickoff participants: ${participantSummary}.`] : []),
+            'This evaluation is read-only and silent: do not use auxiliary collaboration send commands, and do not draft a user-visible reply body for this turn.',
+            `If the anchor message is genuinely requesting host-managed collaboration between the named agents, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"start-protocol","rounds":<positive integer>}`,
+            'Do not combine start-protocol with any attentionUpdate field.',
+            'If collaboration should not start, omit the control footer entirely.',
+            'Do not emit multiple control lines.',
+        ];
+    }
+    return [
+        `Only when you need host-local turn control, append exactly one final non-empty line starting with ${AWAITING_USER_CONTROL_PREFIX}.`,
+        `For ordinary blocked-on-human turns, use: ${AWAITING_USER_CONTROL_PREFIX}{"kind":"awaiting-user","question":"<short question>","reason":"<short reason>"}`,
+        ...(context?.attentionSnapshot
+            ? ['You may add one attentionUpdate field to awaiting-user when you also need an attention change for this channel.']
+            : []),
+        ...attentionLines,
+        ...attentionOnlyLine,
+        'Do not emit multiple control lines, and do not use a control footer for ordinary answers.',
+    ];
 }
 /**
  * Builds the per-turn prompt. Conversation memory is intentionally NOT
@@ -15,8 +220,33 @@ export function buildPrompt(params) {
         'You are replying inside a shared collaboration channel.',
         'Be concise, helpful, and honest about uncertainty.',
         'Do not claim to have performed actions you did not actually perform.',
+        'Keep the visible reply text concise.',
+        ...buildTurnControlPromptLines(params.promptContext),
         `If the user asks who you are, what powers you, or which backend/provider you use, mention that you are currently running on ${providerLabel(params.provider)}.`,
         `Channel: ${params.channelId}`,
+        ...buildInboundMetadataLines({
+            incomingEventKind: params.incomingEventKind,
+            incomingMessageType: params.incomingMessageType,
+            promptContext: params.promptContext,
+        }),
+        ...(() => {
+            const lines = buildCollaborationOutcomeSummaryLines(params.promptContext?.collaborationOutcome);
+            return lines.length > 0 ? ['', ...lines] : [];
+        })(),
+        ...(() => {
+            const lines = buildAttentionSummaryLines(params.promptContext?.attentionSnapshot);
+            return lines.length > 0 ? ['', ...lines] : [];
+        })(),
+        ...(() => {
+            const lines = buildCollaborationCapabilityDeclarationSummaryLines(params.promptContext?.collaborationCapabilities);
+            return lines.length > 0 ? ['', ...lines] : [];
+        })(),
+        ...(() => {
+            const lines = buildMissedCollaborationDiagnosticSummaryLines(params.promptContext?.missedCollaborationDiagnostic);
+            return lines.length > 0 ? ['', ...lines] : [];
+        })(),
+        ...buildSkillRuntimePromptLines(params.promptContext),
+        ...buildLocalhostGatewayPromptLines(params.promptContext),
         '',
         `New message from ${params.incomingAuthorId}:`,
         params.incomingContent,

package/dist/context/task-thread-collaboration.d.ts

@@ -0,0 +1,6 @@
+import type { TaskThreadCollaborationContract } from '../types.js';
+export declare function projectTaskThreadCollaborationContract(params: {
+    incomingMessageType?: string;
+    taskThreadContextActive: boolean;
+}): TaskThreadCollaborationContract | undefined;
+export declare function buildTaskThreadCollaborationSummaryLines(contract: TaskThreadCollaborationContract | undefined): string[];

package/dist/context/task-thread-collaboration.js

@@ -0,0 +1,31 @@
+export function projectTaskThreadCollaborationContract(params) {
+    if (!params.taskThreadContextActive) {
+        return undefined;
+    }
+    const turnRole = params.incomingMessageType?.trim() === 'task_assignment'
+        ? 'assignment'
+        : 'continuation';
+    return {
+        source: 'host-projected',
+        turnRole,
+        taskThreadContextActive: true,
+        mainResult: 'ordinary-final-reply-in-thread',
+        auxiliaryRoute: 'optional-auxiliary-send-or-escalation-only',
+        checkIn: 'status-update-intent-only',
+        blockedWork: 'in-thread-disclosure-only',
+    };
+}
+export function buildTaskThreadCollaborationSummaryLines(contract) {
+    if (!contract) {
+        return [];
+    }
+    return [
+        'Shared task-thread collaboration contract for this turn (projection only; not runtime-authoritative truth).',
+        `Thread role: ${contract.turnRole}`,
+        `Active task-thread context: ${contract.taskThreadContextActive ? 'yes' : 'no'}`,
+        'Main task result: return the ordinary final reply in this task thread.',
+        'Auxiliary send or escalation: optional auxiliary route only, never the main completion path.',
+        'Check-in: status-update intent only; no timer, heartbeat, send-route, scheduler, receipt, or recovery authority is implied here.',
+        'Blocked work: disclose the blocker in-thread through the existing in-thread reply path, if one exists; no blocked-state authority or extra control kind is implied here.',
+    ];
+}