@agent-native/core 0.163.3 → 0.164.1

package/dist/agent/engine/builder-engine.d.ts

@@ -8,10 +8,12 @@
  * concurrency) into structured stop events that carry an upgrade URL when
  * the chat UI needs to prompt the user to upgrade.
  *
- * Credentials come from the gateway lane (`resolveBuilderGatewayCredentials`):
- * the user's own Builder connection when they have one, otherwise the
- * deployment's Builder-credits pair. Base URL is overridable via
- * BUILDER_GATEWAY_BASE_URL.
+ * Interactive users authenticate with Builder OAuth. Existing connections may
+ * keep using BUILDER_PRIVATE_KEY + BUILDER_PUBLIC_KEY until they reconnect.
+ * When neither is present, credentials come from the gateway lane
+ * (`resolveBuilderGatewayCredentials`): the user's own Builder connection,
+ * otherwise the deployment's Builder-credits pair. Base URL is overridable
+ * via BUILDER_GATEWAY_BASE_URL.
  */
 import { type BuilderGatewayLane } from "../../server/credential-provider.js";
 import type { AgentEngine, EngineCapabilities } from "./types.js";

package/dist/agent/engine/builder-engine.js

@@ -8,13 +8,17 @@
  * concurrency) into structured stop events that carry an upgrade URL when
  * the chat UI needs to prompt the user to upgrade.
  *
- * Credentials come from the gateway lane (`resolveBuilderGatewayCredentials`):
- * the user's own Builder connection when they have one, otherwise the
- * deployment's Builder-credits pair. Base URL is overridable via
- * BUILDER_GATEWAY_BASE_URL.
+ * Interactive users authenticate with Builder OAuth. Existing connections may
+ * keep using BUILDER_PRIVATE_KEY + BUILDER_PUBLIC_KEY until they reconnect.
+ * When neither is present, credentials come from the gateway lane
+ * (`resolveBuilderGatewayCredentials`): the user's own Builder connection,
+ * otherwise the deployment's Builder-credits pair. Base URL is overridable
+ * via BUILDER_GATEWAY_BASE_URL.
  */
+import { BUILDER_OAUTH_SCOPE, hasBuilderOAuthSession, markBuilderOAuthReconnectRequired, resolveBuilderOAuthRequestAccess, } from "../../server/builder-oauth.js";
 import { captureError } from "../../server/capture-error.js";
 import { clearBuilderGatewayAuthFailure, isBuilderGatewayDeployConfigured, resolveBuilderGatewayCredentialsDetailed, getBuilderGatewayBaseUrl, recordBuilderGatewayAuthFailure, } from "../../server/credential-provider.js";
+import { getRequestUserEmail } from "../../server/request-context.js";
 import { applyBuilderUtmTrackingParams } from "../../shared/builder-link-tracking.js";
 import { isGPTReasoningModel, normalizeReasoningEffortForModel, } from "../../shared/reasoning-effort.js";
 import { isInBackgroundFunctionRuntime } from "../durable-background.js";
@@ -127,11 +131,35 @@ class BuilderEngine {
     async *stream(opts) {
         const creds = this.configuredCredentials ??
             (await resolveBuilderGatewayCredentialsDetailed());
-        const creditsLane = isBuilderCreditsLane(creds);
-        const authHeader = creds.privateKey ? `Bearer ${creds.privateKey}` : null;
+        const ownerEmail = getRequestUserEmail();
+        let oauthAccess = null;
+        let hasStoredOAuth = false;
+        if (ownerEmail) {
+            hasStoredOAuth = await hasBuilderOAuthSession(ownerEmail);
+            if (hasStoredOAuth) {
+                try {
+                    oauthAccess = await resolveBuilderOAuthRequestAccess({
+                        ownerEmail,
+                        requiredScope: BUILDER_OAUTH_SCOPE,
+                    });
+                }
+                catch {
+                    // coercion-ok: unusable OAuth custody must not fall back to legacy keys.
+                    oauthAccess = null;
+                }
+            }
+        }
+        // Prefer OAuth when present. If OAuth custody exists but is unusable,
+        // do not silently fall back to a legacy private key for the same user.
+        const authHeader = oauthAccess
+            ? `Bearer ${oauthAccess.accessToken}`
+            : !hasStoredOAuth && creds.privateKey
+                ? `Bearer ${creds.privateKey}`
+                : null;
         const spaceId = creds.publicKey;
-        const builderUserId = creds.userId;
-        if (!authHeader || !spaceId) {
+        const builderUserId = oauthAccess ? undefined : creds.userId;
+        const creditsLane = oauthAccess ? false : isBuilderCreditsLane(creds);
+        if (!authHeader || (!oauthAccess && !spaceId)) {
             yield gatewayErrorStop({
                 error: LLM_MISSING_CREDENTIALS_MESSAGE,
                 errorCode: LLM_MISSING_CREDENTIALS_ERROR_CODE,
@@ -246,7 +274,10 @@ class BuilderEngine {
         };
         const gatewayBaseUrl = getBuilderGatewayBaseUrl();
         const gatewayUrl = new URL("messages", gatewayBaseUrl.endsWith("/") ? gatewayBaseUrl : `${gatewayBaseUrl}/`);
-        gatewayUrl.searchParams.set("apiKey", spaceId);
+        // OAuth tokens carry Space identity in the JWT `org` claim. Sending a
+        // client-supplied apiKey/public key is legacy private-key behavior only.
+        if (spaceId && !oauthAccess)
+            gatewayUrl.searchParams.set("apiKey", spaceId);
         const orgLabel = creds.orgName || "unknown-org";
         const tStart = Date.now();
         console.log(`[builder-engine] → POST ${gatewayUrl.origin}${gatewayUrl.pathname} model=${model} tools=${tools.length} org=${orgLabel}`);
@@ -260,7 +291,9 @@ class BuilderEngine {
                     headers: {
                         "Content-Type": "application/json",
                         Authorization: authHeader,
-                        "x-builder-api-key": spaceId,
+                        ...(spaceId && !oauthAccess
+                            ? { "x-builder-api-key": spaceId }
+                            : {}),
                         ...getBuilderGatewayRequestHeaders(),
                         ...(builderUserId ? { "x-builder-user-id": builderUserId } : {}),
                     },
@@ -288,25 +321,32 @@ class BuilderEngine {
             }
             console.log(`[builder-engine] ← ${response.status} ${response.statusText} in ${Date.now() - tStart}ms`);
             if (!response.ok) {
-                yield* emitHttpError(response, { creditsLane, requestShape });
+                yield* emitHttpError(response, {
+                    creditsLane,
+                    requestShape,
+                    recordLegacyCredentialFailure: !oauthAccess,
+                });
                 return;
             }
             // A successful gateway call proves the connected credentials are valid
             // again. Clear any prior auth-failure marker so status / chat-card
             // surfaces stop flagging the connection as broken. This is the only
             // self-healing path for workspace/env-managed credentials, which never
-            // flow through writeBuilderCredentials.
-            try {
-                const creds = this.configuredCredentials ??
-                    (await resolveBuilderGatewayCredentialsDetailed());
-                await clearBuilderGatewayAuthFailure({
-                    privateKey: creds.privateKey,
-                    publicKey: creds.publicKey,
-                });
-            }
-            catch {
-                // Marker clearing is best-effort; a stale marker just means the user
-                // sees "reconnect Builder" until the next successful call clears it.
+            // flow through writeBuilderCredentials. OAuth failures are not tracked
+            // with the legacy private-key fingerprint marker.
+            if (!oauthAccess) {
+                try {
+                    const legacyCreds = this.configuredCredentials ??
+                        (await resolveBuilderGatewayCredentialsDetailed());
+                    await clearBuilderGatewayAuthFailure({
+                        privateKey: legacyCreds.privateKey,
+                        publicKey: legacyCreds.publicKey,
+                    });
+                }
+                catch {
+                    // coercion-ok: clearing the legacy auth-failure marker is best-effort;
+                    // a stale marker only keeps the reconnect CTA until the next success.
+                }
             }
             const contentType = response.headers.get("content-type") ?? "";
             if (contentType.includes("text/html")) {
@@ -341,6 +381,7 @@ class BuilderEngine {
                 gatewayUrl,
                 requestStartedAt: tStart,
                 requestShape,
+                recordLegacyCredentialFailure: !oauthAccess,
             });
         }
         finally {
@@ -398,6 +439,19 @@ function gatewayErrorStop(details, creditsLane, requestShape) {
         ...retry,
     };
 }
+async function recordAuthFailureForCurrentLane(opts) {
+    if (opts.recordLegacyCredentialFailure !== false) {
+        await recordBuilderGatewayAuthFailure({
+            status: opts.status,
+            code: opts.code,
+            message: opts.message,
+        });
+        return;
+    }
+    const ownerEmail = getRequestUserEmail();
+    if (ownerEmail)
+        await markBuilderOAuthReconnectRequired(ownerEmail);
+}
 async function* emitHttpError(response, opts) {
     const status = response.status;
     // Read the body once as text and then try to parse — calling `.json()`
@@ -432,7 +486,12 @@ async function* emitHttpError(response, opts) {
         return;
     }
     if (status === 401 || code === "unauthorized") {
-        await recordBuilderGatewayAuthFailure({ status, code, message });
+        await recordAuthFailureForCurrentLane({
+            recordLegacyCredentialFailure: opts.recordLegacyCredentialFailure,
+            status,
+            code,
+            message,
+        });
         yield stop({
             error: "Builder authentication failed. Reconnect Builder (free tier available) via Settings.",
             errorCode: "builder_auth_error",
@@ -440,7 +499,12 @@ async function* emitHttpError(response, opts) {
         return;
     }
     if (status === 403 && isBuilderCredentialAuthError(message)) {
-        await recordBuilderGatewayAuthFailure({ status, code, message });
+        await recordAuthFailureForCurrentLane({
+            recordLegacyCredentialFailure: opts.recordLegacyCredentialFailure,
+            status,
+            code,
+            message,
+        });
         yield stop({
             error: "Builder authentication failed. Reconnect Builder (free tier available) via Settings.",
             errorCode: "builder_auth_error",
@@ -709,7 +773,8 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                                                 classifyTerminalErrorCode(String(errMsg))));
                         console.error(`[builder-engine] stop reason=error model=${model} code=${errCode ?? "(none)"} requestId=${gatewayRequestId ?? "(none)"} error=${errMsg}`);
                         if (isCredentialAuthError) {
-                            await recordBuilderGatewayAuthFailure({
+                            await recordAuthFailureForCurrentLane({
+                                recordLegacyCredentialFailure: captureContext.recordLegacyCredentialFailure,
                                 code: typeof gatewayErrCode === "string" ? gatewayErrCode : errCode,
                                 message: String(errMsg),
                             });

package/dist/agent/engine/registry.js

@@ -9,7 +9,9 @@
  */
 import { createRequire } from "node:module";
 import { getAppConfig } from "../../app-config/index.js";
+import { BUILDER_OAUTH_SCOPE, hasBuilderOAuthSession, resolveBuilderOAuthRequestAccess, } from "../../server/builder-oauth.js";
 import { assertCredentialStoreReadable, canUseDeployCredentialFallbackForRequest, getBuilderCredentialAuthFailure, getProviderCredentialAuthFailure, readDeployCredentialEnv, resolveBuilderCredentialsDetailed, resolveBuilderGatewayCredentialsDetailed, resolveSecret, } from "../../server/credential-provider.js";
+import { getRequestUserEmail } from "../../server/request-context.js";
 import { getSetting } from "../../settings/store.js";
 import { getAgentAppModelDefaultForCurrentRequest } from "../app-model-defaults.js";
 import { OLLAMA_BASE_URL_ENV_VAR, OPENAI_BASE_URL_ENV_VAR, } from "./openai-compatible-endpoint.js";
@@ -556,6 +558,20 @@ async function resolveProviderBaseUrl(envVar) {
  * whose org-shared keys exist but were unreadable.
  */
 async function hasUsableBuilderConnection(identity) {
+    const ownerEmail = identity?.userEmail?.trim().toLowerCase() || getRequestUserEmail();
+    if (ownerEmail && (await hasBuilderOAuthSession(ownerEmail))) {
+        try {
+            return Boolean(await resolveBuilderOAuthRequestAccess({
+                ownerEmail,
+                requiredScope: BUILDER_OAUTH_SCOPE,
+            }));
+        }
+        catch {
+            // coercion-ok: custody present but unusable is "not usable", not absent;
+            // reconnect UX is owned by /builder/status, not this boolean probe.
+            return false;
+        }
+    }
     const creds = await resolveBuilderCredentialsDetailed(identity);
     assertCredentialStoreReadable(creds);
     return Boolean(creds.privateKey && creds.publicKey);

package/dist/cli/code-agent-agent-tools.d.ts

@@ -0,0 +1,2 @@
+import type { ActionEntry } from "../agent/production-agent.js";
+export declare function createCodeAgentAgentTools(runId: string, cwd: string, runTitle?: string): Record<string, ActionEntry>;

package/dist/cli/code-agent-agent-tools.js

@@ -0,0 +1,188 @@
+import { createCodeAgentThread, listCodeAgentThreadSummaries, messageCodeAgentThread, } from "./code-agent-collaboration.js";
+import { createCodeAgentSchedule, deleteCodeAgentSchedule, listCodeAgentSchedules, updateCodeAgentSchedule, } from "./code-agent-schedules.js";
+export function createCodeAgentAgentTools(runId, cwd, runTitle) {
+    return {
+        "manage-schedules": {
+            tool: {
+                description: "Create and manage durable local desktop schedules. A global schedule starts a new Agent-Native Code thread on every interval. A thread schedule queues a message into an existing thread. Use intervalMinutes for intervals such as 360 for every 6 hours.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        action: {
+                            type: "string",
+                            enum: ["create", "list", "update", "delete"],
+                            description: "The schedule operation.",
+                        },
+                        scheduleId: {
+                            type: "string",
+                            description: "Required for update or delete.",
+                        },
+                        name: {
+                            type: "string",
+                            description: "Human-readable schedule name.",
+                        },
+                        prompt: {
+                            type: "string",
+                            description: "Instructions sent to the new or existing thread.",
+                        },
+                        scope: {
+                            type: "string",
+                            enum: ["global", "thread"],
+                            description: "Whether to start a new thread or message an existing one.",
+                        },
+                        targetRunId: {
+                            type: "string",
+                            description: "Existing thread id when scope is thread.",
+                        },
+                        intervalMinutes: {
+                            type: "number",
+                            description: "Whole minutes between runs, for example 360 is every 6 hours.",
+                        },
+                        enabled: {
+                            type: "boolean",
+                            description: "Whether the schedule is active.",
+                        },
+                    },
+                    required: ["action"],
+                },
+            },
+            run: async (args) => {
+                try {
+                    switch (args.action) {
+                        case "list":
+                            return JSON.stringify({
+                                ok: true,
+                                schedules: listCodeAgentSchedules(),
+                            });
+                        case "create": {
+                            const schedule = createCodeAgentSchedule({
+                                name: String(args.name ?? ""),
+                                prompt: String(args.prompt ?? ""),
+                                scope: args.scope === "thread" ? "thread" : "global",
+                                targetRunId: typeof args.targetRunId === "string"
+                                    ? args.targetRunId
+                                    : undefined,
+                                intervalMinutes: Number(args.intervalMinutes),
+                                enabled: args.enabled !== false,
+                                createdByRunId: runId,
+                            });
+                            return JSON.stringify({ ok: true, schedule });
+                        }
+                        case "update": {
+                            const scheduleId = String(args.scheduleId ?? "").trim();
+                            if (!scheduleId)
+                                return "Error: scheduleId is required for update.";
+                            const schedule = updateCodeAgentSchedule(scheduleId, {
+                                ...(typeof args.name === "string" ? { name: args.name } : {}),
+                                ...(typeof args.prompt === "string"
+                                    ? { prompt: args.prompt }
+                                    : {}),
+                                ...(args.scope === "global" || args.scope === "thread"
+                                    ? { scope: args.scope }
+                                    : {}),
+                                ...(typeof args.targetRunId === "string"
+                                    ? { targetRunId: args.targetRunId }
+                                    : {}),
+                                ...(args.intervalMinutes !== undefined
+                                    ? { intervalMinutes: Number(args.intervalMinutes) }
+                                    : {}),
+                                ...(typeof args.enabled === "boolean"
+                                    ? { enabled: args.enabled }
+                                    : {}),
+                            });
+                            return schedule
+                                ? JSON.stringify({ ok: true, schedule })
+                                : `Error: schedule not found: ${scheduleId}`;
+                        }
+                        case "delete": {
+                            const scheduleId = String(args.scheduleId ?? "").trim();
+                            if (!scheduleId)
+                                return "Error: scheduleId is required for delete.";
+                            return JSON.stringify({
+                                ok: deleteCodeAgentSchedule(scheduleId),
+                                scheduleId,
+                            });
+                        }
+                        default:
+                            return "Error: action must be create, list, update, or delete.";
+                    }
+                }
+                catch (error) {
+                    return `Error: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            },
+        },
+        "manage-agent-threads": {
+            tool: {
+                description: "List threads, create a new Agent-Native Code thread, or queue a message to another thread. Messages are durable and include a source-agent marker in the recipient transcript.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        action: {
+                            type: "string",
+                            enum: ["list", "create", "message"],
+                            description: "The thread operation.",
+                        },
+                        query: {
+                            type: "string",
+                            description: "Optional title/id filter for list.",
+                        },
+                        title: { type: "string", description: "Title for a new thread." },
+                        prompt: {
+                            type: "string",
+                            description: "Initial prompt or message.",
+                        },
+                        targetRunId: {
+                            type: "string",
+                            description: "Recipient thread id when action is message.",
+                        },
+                    },
+                    required: ["action"],
+                },
+            },
+            run: async (args) => {
+                try {
+                    switch (args.action) {
+                        case "list":
+                            return JSON.stringify({
+                                ok: true,
+                                threads: listCodeAgentThreadSummaries(typeof args.query === "string" ? args.query : undefined),
+                            });
+                        case "create": {
+                            const result = createCodeAgentThread({
+                                title: typeof args.title === "string" ? args.title : undefined,
+                                prompt: String(args.prompt ?? ""),
+                                cwd,
+                                sourceRunId: runId,
+                                sourceRunTitle: runTitle,
+                            });
+                            return JSON.stringify({
+                                ok: true,
+                                thread: result.run,
+                                event: result.event,
+                            });
+                        }
+                        case "message": {
+                            const result = messageCodeAgentThread({
+                                targetRunId: String(args.targetRunId ?? ""),
+                                prompt: String(args.prompt ?? ""),
+                                sourceRunId: runId,
+                                sourceRunTitle: runTitle,
+                            });
+                            return JSON.stringify({
+                                ok: true,
+                                thread: result.run,
+                                event: result.event,
+                            });
+                        }
+                        default:
+                            return "Error: action must be list, create, or message.";
+                    }
+                }
+                catch (error) {
+                    return `Error: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            },
+        },
+    };
+}

package/dist/cli/code-agent-collaboration.d.ts

@@ -0,0 +1,34 @@
+import { type CodeAgentPermissionMode, type CodeAgentRunRecord, type CodeAgentTranscriptEvent } from "./code-agent-runs.js";
+export interface CodeAgentThreadSummary {
+    id: string;
+    goalId: string;
+    title: string;
+    status: CodeAgentRunRecord["status"];
+    updatedAt: string;
+    source?: string;
+}
+export interface CreateCodeAgentThreadInput {
+    title?: string;
+    prompt: string;
+    cwd: string;
+    permissionMode?: CodeAgentPermissionMode;
+    sourceRunId: string;
+    sourceRunTitle?: string;
+}
+export interface CreateCodeAgentThreadResult {
+    run: CodeAgentRunRecord;
+    event: CodeAgentTranscriptEvent;
+}
+export interface MessageCodeAgentThreadInput {
+    targetRunId: string;
+    prompt: string;
+    sourceRunId: string;
+    sourceRunTitle?: string;
+}
+export interface MessageCodeAgentThreadResult {
+    run: CodeAgentRunRecord;
+    event: CodeAgentTranscriptEvent;
+}
+export declare function listCodeAgentThreadSummaries(query?: string): CodeAgentThreadSummary[];
+export declare function createCodeAgentThread(input: CreateCodeAgentThreadInput): CreateCodeAgentThreadResult;
+export declare function messageCodeAgentThread(input: MessageCodeAgentThreadInput): MessageCodeAgentThreadResult;

package/dist/cli/code-agent-collaboration.js

@@ -0,0 +1,104 @@
+import { appendCodeAgentTranscriptEvent, createCodeAgentRunRecord, getCodeAgentRunRecord, listCodeAgentRunRecords, queueCodeAgentFollowUp, updateCodeAgentRunRecord, } from "./code-agent-runs.js";
+export function listCodeAgentThreadSummaries(query) {
+    const normalizedQuery = query?.trim().toLowerCase();
+    return listCodeAgentRunRecords()
+        .filter((run) => {
+        if (!normalizedQuery)
+            return true;
+        return `${run.title} ${run.id}`.toLowerCase().includes(normalizedQuery);
+    })
+        .map((run) => ({
+        id: run.id,
+        goalId: run.goalId,
+        title: run.title,
+        status: run.status,
+        updatedAt: run.updatedAt,
+        source: typeof run.metadata?.source === "string"
+            ? run.metadata.source
+            : undefined,
+    }));
+}
+export function createCodeAgentThread(input) {
+    const prompt = requiredText(input.prompt, "Thread prompt");
+    const title = requiredText(input.title ?? titleFromPrompt(prompt), "Thread title");
+    const now = new Date().toISOString();
+    const run = createCodeAgentRunRecord({
+        goalId: "task",
+        title,
+        subtitle: "Created by another agent",
+        status: "queued",
+        phase: "queued",
+        permissionMode: input.permissionMode ?? "full-auto",
+        cwd: input.cwd,
+        metadata: {
+            source: "agent",
+            sourceRunId: input.sourceRunId,
+            ...(input.sourceRunTitle ? { sourceRunTitle: input.sourceRunTitle } : {}),
+            createdByAgent: true,
+            startRequested: true,
+            createdAtByAgent: now,
+            initialPrompt: prompt,
+        },
+    });
+    const event = appendCodeAgentTranscriptEvent({
+        runId: run.id,
+        kind: "user",
+        message: prompt,
+        metadata: {
+            source: "agent",
+            sourceRunId: input.sourceRunId,
+            ...(input.sourceRunTitle ? { sourceRunTitle: input.sourceRunTitle } : {}),
+            threadCreated: true,
+        },
+    });
+    return { run, event };
+}
+export function messageCodeAgentThread(input) {
+    const prompt = requiredText(input.prompt, "Thread message");
+    if (!input.targetRunId || input.targetRunId === input.sourceRunId) {
+        throw new Error("Choose a different target thread.");
+    }
+    const target = getCodeAgentRunRecord(input.targetRunId);
+    if (!target)
+        throw new Error(`Thread not found: ${input.targetRunId}`);
+    const event = appendCodeAgentTranscriptEvent({
+        runId: target.id,
+        kind: "user",
+        message: prompt,
+        metadata: {
+            source: "agent",
+            sourceRunId: input.sourceRunId,
+            ...(input.sourceRunTitle ? { sourceRunTitle: input.sourceRunTitle } : {}),
+        },
+    });
+    const followUp = queueCodeAgentFollowUp({
+        runId: target.id,
+        prompt,
+        mode: "queued",
+        eventId: event.id,
+        source: "agent",
+    });
+    if (!followUp)
+        throw new Error(`Could not queue a message for ${target.id}`);
+    const run = updateCodeAgentRunRecord(target.id, {
+        metadata: {
+            startRequested: true,
+            lastMessageSource: "agent",
+            lastMessageSourceRunId: input.sourceRunId,
+        },
+    }) ?? target;
+    return { run, event };
+}
+function requiredText(value, label) {
+    const text = typeof value === "string" ? value.trim() : "";
+    if (!text)
+        throw new Error(`${label} is required.`);
+    return text.slice(0, 8_000);
+}
+function titleFromPrompt(prompt) {
+    const firstLine = prompt.split(/\r?\n/, 1)[0]?.trim() ?? "";
+    const normalized = firstLine.replace(/^\/+[a-z0-9-]+\s*/i, "").trim();
+    if (!normalized)
+        return "Agent-created thread";
+    return normalized.length > 72 ? `${normalized.slice(0, 69)}...` : normalized;
+}

package/dist/cli/code-agent-executor.js

@@ -14,6 +14,7 @@ import { buildMergedConfig, McpClientManager, mcpToolsToActionEntries, } from ".
 import { readAgentsBundleFromFs, generateDevelopmentSkillsPromptBlock, } from "../server/agents-bundle.js";
 import { getAmbientOrgId, getAmbientUserEmail, runWithRequestContext, } from "../server/request-context.js";
 import { isReasoningEffort, } from "../shared/reasoning-effort.js";
+import { createCodeAgentAgentTools } from "./code-agent-agent-tools.js";
 import { createAgentNativeConfigContext, loadResolvedAgentNativeConfig, } from "../vite/agent-native-config-loader.js";
 import { runClaudeCodeParticipant, } from "./claude-code-participant.js";
 import { codexMcpConfigArgs, mergeCodeAgentMcpConfig, restrictCodeAgentMcpConfig, } from "./code-agent-mcp-config.js";
@@ -2201,6 +2202,10 @@ Current run mode: ${mode} mode (${permissionMode}).
 - In an Agent-Native app or workspace, also run \`pnpm agent-native:doctor\` (or \`pnpm doctor\`) after source changes. Treat every finding as a fix-required security issue; do not disable a guard without a reviewer-readable reason.
 - Do not claim a change works, tests pass, or a build succeeds unless you actually ran it and saw the result. If you could not verify something, say exactly what is unverified and why.
 
+# Schedules and cooperating threads
+
+In Auto mode, use \`manage-schedules\` for durable local desktop schedules. A global schedule starts a fresh thread on each interval; a thread schedule queues a message into an existing thread. Use \`intervalMinutes: 360\` for every 6 hours. Use \`manage-agent-threads\` to list threads, create a peer thread, or message another thread. Messages include source-agent metadata so the recipient can link back to the sender.
+
 # Tools beyond the basics
 
 - Use \`tool-search\` when you need a capability that may come from MCP, including browser automation or computer control.
@@ -2278,6 +2283,7 @@ function createLocalCodeAgentActions(cwd, permissionMode, runId, onToolMetadata,
             read: actions.read,
         };
     }
+    Object.assign(actions, createCodeAgentAgentTools(runId, cwd));
     return actions;
 }
 function resolveCodeAgentToolProfile(value) {

package/dist/cli/code-agent-schedules.d.ts

@@ -0,0 +1,54 @@
+export type CodeAgentScheduleScope = "global" | "thread";
+export type CodeAgentScheduleStatus = "queued" | "completed" | "errored";
+export interface CodeAgentScheduleRecord {
+    schemaVersion: 1;
+    id: string;
+    name: string;
+    prompt: string;
+    scope: CodeAgentScheduleScope;
+    targetRunId?: string;
+    intervalMinutes: number;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+    nextRunAt: string;
+    lastRunAt?: string;
+    lastStatus?: CodeAgentScheduleStatus;
+    lastError?: string;
+    lastTriggeredRunId?: string;
+    createdByRunId?: string;
+}
+export interface CreateCodeAgentScheduleInput {
+    name: string;
+    prompt: string;
+    scope?: CodeAgentScheduleScope;
+    targetRunId?: string;
+    intervalMinutes: number;
+    enabled?: boolean;
+    createdByRunId?: string;
+    now?: Date;
+}
+export interface UpdateCodeAgentScheduleInput {
+    name?: string;
+    prompt?: string;
+    scope?: CodeAgentScheduleScope;
+    targetRunId?: string | null;
+    intervalMinutes?: number;
+    enabled?: boolean;
+}
+export interface CodeAgentScheduleRunPatch {
+    lastRunAt: string;
+    lastStatus: CodeAgentScheduleStatus;
+    nextRunAt?: string;
+    lastError?: string | null;
+    lastTriggeredRunId?: string;
+}
+export declare function codeAgentSchedulesPath(): string;
+export declare function listCodeAgentSchedules(): CodeAgentScheduleRecord[];
+export declare function getCodeAgentSchedule(scheduleId: string): CodeAgentScheduleRecord | null;
+export declare function createCodeAgentSchedule(input: CreateCodeAgentScheduleInput): CodeAgentScheduleRecord;
+export declare function updateCodeAgentSchedule(scheduleId: string, input: UpdateCodeAgentScheduleInput): CodeAgentScheduleRecord | null;
+export declare function deleteCodeAgentSchedule(scheduleId: string): boolean;
+export declare function markCodeAgentScheduleRun(scheduleId: string, patch: CodeAgentScheduleRunPatch): CodeAgentScheduleRecord | null;
+export declare function isCodeAgentScheduleDue(schedule: CodeAgentScheduleRecord, now?: Date): boolean;
+export declare function nextCodeAgentScheduleRunAt(schedule: CodeAgentScheduleRecord, now?: Date): string;