@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/cli/program.js

@@ -8,14 +8,18 @@ import { fastagentVersion } from "../version.js";
 import { buildProgram } from "./kernel.js";
 // Help groups (clig: most common commands first) — the authoring loop leads, operations close.
 // Shared flags — same name, same meaning, on every command that supports them (clig: consistency).
-const DIR_ARG = { name: "[dir]", description: "workspace directory", default: "." };
+const DIR_ARG = {
+    name: "[dir]",
+    description: "workspace directory (the agent is here, or in a directory inside it)",
+    default: ".",
+};
 const MODEL = {
     flags: "--model <provider/modelId>",
     description: "model override (precedence: --model > FASTAGENT_MODEL > config)",
 };
 const AUTH_PATH = {
     flags: "--auth-path <file>",
-    description: "credentials file (default: <state root>/auth.json; env: FASTAGENT_AUTH_PATH)",
+    description: "credentials file (default: <agent dir>/.secrets/auth.json; env: FASTAGENT_AUTH_PATH)",
 };
 const JSON_FLAG = { flags: "--json", description: "machine-readable JSON output" };
 const NO_INPUT = {
@@ -26,37 +30,49 @@ const PORT = { flags: "--port <n>", description: "HTTP port" };
 const TUNNEL = {
     flags: "--tunnel",
     description: "expose a public HTTPS URL via a Cloudflare quick tunnel (needs cloudflared) and auto-register " +
-        "webhook channels (telegram, feishu, lark; github prints the URL) — for hosting a bot from your " +
+        "webhook channels (telegram, onboarded slack, feishu, lark; github/manual slack print the URL) — for hosting a bot from your " +
         "own box without deploying (the quick-tunnel URL is ephemeral, not for production)",
 };
 const init = {
     name: "init",
     summary: "scaffold a runnable agent and install its dependencies",
-    description: "Scaffold a runnable agent in dir (default .) and run npm install. Default is a self-iterating " +
-        "agent: persona.md (its identity), a writing-great-skills example skill, a fetch-url code tool, " +
-        "config, package.json, .gitignore. Never overwrites existing files; an existing AGENTS.md is kept " +
-        "as project context.",
+    description: "Scaffold a runnable agent and run npm install. By default the agent goes into ./fastagent/ in dir " +
+        "(default .; --agent-dir names it otherwise) — the rest of the directory gets zero writes, and it is " +
+        "the WORKSPACE the agent works ON when you point fastagent there. Default content is a " +
+        "self-iterating agent: persona.md (its identity), a writing-great-skills " +
+        "example skill, a fetch-url code tool, config, package.json, .gitignore. An existing AGENTS.md is " +
+        "kept as project context.",
     args: [DIR_ARG],
     flags: [
         { flags: "--minimal", description: "persona.md + the example skill + config only (no code tool / package.json)" },
         { flags: "--no-install", description: "scaffold everything but skip npm install" },
-        { flags: "--flat", description: "force the flat layout (skip host-signal detection)", conflicts: ["agentDir"] },
-        { flags: "--agent-dir <name>", description: "force the agent kit into ./<name>" },
+        { flags: "--agent-dir <name>", description: "name the agent directory (default fastagent; . = dir itself)" },
+        {
+            flags: "--flat",
+            description: "alias for --agent-dir . — the directory IS the agent; keeps existing files",
+            // Two spellings of ONE knob: `--flat --agent-dir bot` names the same thing twice with different
+            // values, which is a usage error, not a precedence question to settle silently.
+            conflicts: ["agentDir"],
+        },
     ],
     examples: [
-        { cmd: "fastagent init my-agent", note: "a new agent dir, ready to dev" },
-        { cmd: "fastagent init", note: "initialize the current directory" },
+        { cmd: "fastagent init", note: "the agent lands in ./fastagent/" },
+        { cmd: "fastagent init my-project", note: "my-project/fastagent/ (created)" },
+        { cmd: "fastagent init . --agent-dir bot", note: "./bot/ — any name works" },
+        { cmd: "fastagent init . --flat", note: "this repo IS the agent" },
     ],
-    notes: 'Layout: flat by default ("a directory is an agent"); when an existing toolchain/deploy claims ' +
-        "the directory (tsconfig/framework config, a non-JS build manifest like " +
-        "go.mod/pyproject.toml/Cargo.toml, Dockerfile/fly/railway, or occupied tools/, channels/, or " +
-        "skills/), the kit goes into ./agent and config.agentDir points there — the reason is printed, " +
-        "no prompt.",
+    notes: "An agent is a directory holding a fastagent.config.* — never its NAME, so --agent-dir can call it " +
+        "anything (the name decides only which agent answers when a workspace holds several: see " +
+        "FASTAGENT_AGENT). What the agent works ON (its cwd, where its AGENTS.md context is read from) is " +
+        "whatever directory you later point fastagent at: point at the project and the agent inside it " +
+        "serves with the project as its workspace; point at the agent directory (all a deployed box may " +
+        "hold) and it works on itself. A directory resolves to ONE agent, at it or one level inside.",
     run: async (args, f) => (await import("./commands/init.js")).runInit(args[0], {
         minimal: f.minimal === true,
         install: f.install !== false,
-        flat: f.flat === true,
-        agentDir: f.agentDir,
+        // `--flat` is the spelling for the common case of the same knob (they conflict, so only one is
+        // ever set); both land in ONE value, so the scaffolder never sees two ways to say ".".
+        agentDir: f.flat === true ? "." : typeof f.agentDir === "string" ? f.agentDir : undefined,
     }),
 };
 const dev = {
@@ -64,8 +80,8 @@ const dev = {
     summary: "serve the agent locally, restarting on code edits",
     description: "Assemble the agent in dir (default .) and serve a local HTTP channel. persona.md/AGENTS.md/skills " +
         "are re-read every turn (edits go live next turn); edits to code inputs — tools/, channels/, " +
-        "fastagent.config.*, package.json, .env — restart the worker. Files the agent writes as work " +
-        "product never trigger a restart.",
+        "fastagent.config.*, package.json, .secrets/.env — restart the worker. Files the agent writes as " +
+        "work product never trigger a restart.",
     args: [DIR_ARG],
     flags: [
         PORT,
@@ -77,7 +93,7 @@ const dev = {
     ],
     examples: [
         { cmd: "fastagent dev" },
-        { cmd: "fastagent dev --tunnel", note: "public URL + auto-registered webhooks" },
+        { cmd: "fastagent dev --tunnel", note: "public URL + registered/guided webhooks" },
     ],
     run: async (args, f) => (await import("./commands/dev.js")).runDev(args[0], {
         port: f.port,
@@ -88,16 +104,38 @@ const dev = {
         input: f.input !== false,
     }),
 };
+const attach = {
+    name: "attach",
+    summary: "watch a session's live events from a running serve and steer it",
+    description: "Attach to a session served by a running dev/start with `sessionControl: true` in the config: " +
+        "stream its live events (text, tools, run boundaries), steer the active run by typing — or, with " +
+        "no run active, start one (detaching cancels a run YOU started) — /abort to stop a run. Discovers " +
+        "the local endpoint from <stateRoot>/control.json; --url/--token reach a remote serve. The same " +
+        "wire protocol a Web panel or desktop app uses.",
+    args: [{ name: "<session>", description: "the session id to attach to" }, DIR_ARG],
+    flags: [
+        { flags: "--url <url>", description: "control endpoint (skip control.json discovery)" },
+        { flags: "--token <token>", description: "bearer token for --url" },
+    ],
+    examples: [{ cmd: "fastagent attach tg-chat-42" }],
+    run: async (args, f) => (await import("./commands/attach.js")).runAttach(args[0], args[1], {
+        url: f.url,
+        token: f.token,
+    }),
+};
 const chat = {
     name: "chat",
     summary: "open the SAME assembled agent in pi's interactive TUI",
     description: "Open the SAME assembled agent in pi's interactive TUI (the real harness, not a crude REPL) — to " +
-        "try it locally before serving. Same model/tool/skill resolution as dev; pi handles login, " +
-        "sessions, and /resume natively.",
+        "try it locally before serving. Same model/tool/skill/auth resolution as dev; pi handles " +
+        "rendering, sessions, and /resume natively (its /login writes to the same fastagent auth file).",
     args: [DIR_ARG],
-    flags: [MODEL],
+    flags: [MODEL, AUTH_PATH],
     examples: [{ cmd: "fastagent chat" }],
-    run: async (args, f) => (await import("./commands/chat.js")).runChat(args[0], { model: f.model }),
+    run: async (args, f) => (await import("./commands/chat.js")).runChat(args[0], {
+        model: f.model,
+        authPath: f.authPath,
+    }),
 };
 const info = {
     name: "info",
@@ -192,14 +230,14 @@ const start = {
     ],
     notes: "Precedence chains:\n" +
         "  port:     --port > PORT env > fastagent.config.ts http.port > 8787\n" +
-        "  state:    FASTAGENT_STATE_DIR > <dir>/.fastagent — the ONE machine-state\n" +
-        "            root (auth, sessions, channel state all derive from it); point\n" +
-        "            it at a mounted volume so a redeploy that replaces the\n" +
-        "            directory never wipes state\n" +
+        "  state:    FASTAGENT_STATE_DIR > <agent dir>/.state — mutable machine state\n" +
+        "            (sessions, channel state, schedule state); point it at a mounted\n" +
+        "            volume so a redeploy that replaces the directory never wipes it\n" +
+        "  secrets:  FASTAGENT_SECRETS_DIR > <agent dir>/.secrets — .env + auth.json\n" +
         "  sessions: --sessions-dir > FASTAGENT_SESSIONS_DIR > <state>/sessions\n" +
-        "  auth:     --auth-path > FASTAGENT_AUTH_PATH > <state>/auth.json\n" +
-        "            (project-level; point it at ~/.fastagent/auth.json to share one\n" +
-        "            credential across projects)",
+        "  auth:     --auth-path > FASTAGENT_AUTH_PATH > <secrets>/auth.json\n" +
+        "            (project-level; point it at ~/.fastagent/.secrets/auth.json to\n" +
+        "            share one credential across projects)",
     run: async (args, f) => (await import("./commands/start.js")).runStart(args[0], {
         port: f.port,
         model: f.model,
@@ -211,37 +249,70 @@ const start = {
 };
 /** The retired app-creation flag — parsed so it can explain itself, hidden from help. */
 const CREATE_APP = { flags: "--create-app", description: "(retired)", hidden: true };
+const INGRESS = {
+    flags: "--ingress <mode>",
+    description: "Feishu/Lark ingress: websocket or webhook (interactive when omitted)",
+};
+const GROUP_BEHAVIOR = {
+    flags: "--group-behavior <behavior>",
+    description: "Slack/Feishu/Lark groups: context (recommended) or mentions (least privilege)",
+};
+const NO_ONBOARD = {
+    flags: "--no-onboard",
+    description: "Slack: scaffold only; skip internal-app creation/OAuth",
+};
+const REPLACE_CONFIG = {
+    flags: "--replace-config",
+    description: "Slack: replace the local App Configuration token pair (repairs automatic dev/deploy Request URL " +
+        "updates after the tokens expire or are revoked; runs on the machine that onboarded the app)",
+};
 const channelSub = (kind, summary, description, notes) => ({
     name: kind,
     summary,
     description,
     args: [DIR_ARG],
-    flags: [CREATE_APP],
+    flags: [
+        CREATE_APP,
+        ...(kind === "feishu" || kind === "lark"
+            ? [INGRESS, GROUP_BEHAVIOR]
+            : kind === "slack"
+                ? [GROUP_BEHAVIOR, NO_ONBOARD, REPLACE_CONFIG]
+                : []),
+    ],
     examples: [{ cmd: `fastagent add ${kind}` }],
     ...(notes ? { notes } : {}),
-    run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], { createApp: f.createApp === true }),
+    run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], {
+        createApp: f.createApp === true,
+        ingress: f.ingress,
+        groupBehavior: f.groupBehavior,
+        onboard: f.onboard !== false,
+        replaceConfig: f.replaceConfig === true,
+    }),
 });
 const add = {
     name: "add",
-    summary: "connect a channel (github, telegram, feishu, lark) or vendor a skill",
-    description: "Scaffold channels/<kind>.ts — third-party adapter glue with the policy to edit (github maps " +
-        "events in on(); telegram/feishu/lark route in the optional route()) — or vendor an Agent Skills " +
+    summary: "connect a channel (github, telegram, slack, feishu, lark) or vendor a skill",
+    description: "Scaffold channels/<kind>.ts — first-party adapter glue with the policy to edit (github maps " +
+        "events in on(); telegram/slack/feishu/lark route in the optional route()) — or vendor an Agent Skills " +
         "skill into skills/<name>/.",
     subcommands: [
         channelSub("github", "scaffold the GitHub webhook channel (issues/PRs → agent turns)", "Scaffold channels/github.ts — webhook adapter glue that maps repository events (issues, PRs, " +
             "comments) to agent turns in its on() policy."),
         channelSub("telegram", "scaffold the Telegram bot channel (durable turns, live preview)", "Scaffold channels/telegram.ts — the Telegram bot channel with durable turns, a live-preview " +
             "message pump, and an optional route() policy."),
-        channelSub("feishu", "scaffold the Feishu channel AND create/configure the platform app", "Scaffold channels/feishu.ts AND create/configure the Feishu platform app (scan-to-create), " +
-            "writing credentials to .env.", "Feishu (open.feishu.cn) is the canonical implementation. `add feishu` also CREATES + " +
-            'configures the platform app (confirm a link in the app — the platform\'s "scan to create" ' +
-            "flow; one version-publish action remains) and writes credentials to .env; a persisted " +
-            "ID/Secret pair resumes missing-Token setup instead of creating another app."),
-        channelSub("lark", "scaffold the Lark (international) channel with guided credential setup", "Scaffold channels/lark.ts — the Lark international profile over the Feishu engine — and guide " +
-            "credential setup against the intl developer console.", "Lark international (open.larksuite.com) is Feishu's compatibility profile with degraded " +
-            "control-plane setup: opens the intl developer console only for a new/partial pair, validates " +
-            "App ID/Secret, then probes webhook-mode + Token automation; an explicit config-route 404 " +
-            "falls back to a hidden Token prompt + manual mode/URL setup."),
+        channelSub("slack", "scaffold the Slack Events API channel (files, threads, context, live preview)", "Choose group visibility, scaffold channels/slack.ts plus slack-send.ts, create a single-workspace " +
+            "internal Slack app from a manifest, and install it through OAuth. The channel provides signed " +
+            "Events API ingress, durable turns, files, threads, context, and an edited live preview.", "Automated onboarding requires Slack App Configuration access + refresh tokens and a temporary " +
+            "cloudflared tunnel. They stay in owner-readable local state and are never deployed; --no-onboard " +
+            "keeps the explicit manual/scaffold-only path."),
+        channelSub("feishu", "scaffold the Feishu channel AND create/configure the platform app", "Choose WebSocket or webhook, scaffold channels/feishu.ts, and create/configure the Feishu app " +
+            "through scan-to-create, writing the matching credentials to .env.", "Feishu (open.feishu.cn) is the canonical implementation. WebSocket needs only App ID/Secret and " +
+            "no public URL; webhook additionally captures the Verification Token through a temporary tunnel. " +
+            "Context-aware groups (recommended) request admin approval for im:message.group_msg before publish."),
+        channelSub("lark", "scaffold the Lark (international) channel with guided credential setup", "Choose WebSocket or webhook, scaffold channels/lark.ts, and guide credential setup against the " +
+            "international developer console.", "Lark international (open.larksuite.com) is Feishu's compatibility profile. WebSocket stops after " +
+            "App ID/Secret validation; webhook and recommended context-aware group setup probe config " +
+            "automation and fall back to explicit manual steps on the international config-route 404."),
         {
             name: "skill",
             summary: "vendor an Agent Skills skill into skills/<name>/ (copied in, git-tracked)",
@@ -269,19 +340,22 @@ const add = {
 };
 const deploy = {
     name: "deploy",
-    summary: "generate deploy artifacts + a runbook for docker, fly, or railway (--run drives it)",
+    summary: "generate deploy artifacts + a runbook for docker, fly, railway, or agentcore (--run drives it)",
     description: "Generate Dockerfile/.dockerignore plus the target config and print an ordered runbook. " +
         "docker: fastagent.compose.yml, loopback port, persistent state volume. fly: fly.toml " +
         "(autostop=suspend, state→volume). railway: railway.json (healthcheck /health); its " +
-        "volume/variables/App-Sleeping are dashboard/CLI steps the runbook states. Durable ingress " +
-        "remains operator-owned.",
-    args: [{ name: "<host>", description: "deploy target", choices: ["docker", "fly", "railway"] }, DIR_ARG],
+        "volume/variables/App-Sleeping are dashboard/CLI steps the runbook states. agentcore: one " +
+        "CloudFormation stack (AWS Bedrock AgentCore Runtime + forwarder Lambda for webhooks + " +
+        "EventBridge rules for schedules; linux/arm64 image built locally). Durable ingress " +
+        "remains operator-owned (agentcore's forwarder URL is the exception — the stack owns it).",
+    args: [{ name: "<host>", description: "deploy target", choices: ["docker", "fly", "railway", "agentcore"] }, DIR_ARG],
     flags: [
         {
             flags: "--run",
             description: "drive the target CLI to completion. Docker runs `docker compose up -d --build`; with a tunnel " +
                 "service, reads its URL and registers webhooks. Fly/Railway provision app/service + volume + " +
-                "secrets + deploy + webhook setup. Carries your local credential (env key or OAuth auth.json). " +
+                "secrets + deploy + webhook setup. AgentCore builds/pushes the arm64 image and deploys the " +
+                "stack (aws + docker CLIs). Carries your local credential (env key or OAuth auth.json). " +
                 "Stops at a gate (missing CLI/daemon/login/secret) with one actionable line. Without it: prints " +
                 "the runbook",
         },
@@ -306,11 +380,13 @@ const deploy = {
         },
         MODEL,
         AUTH_PATH,
+        NO_INPUT,
     ],
     examples: [
         { cmd: "fastagent deploy fly --run", note: "provision + deploy + webhooks" },
         { cmd: "fastagent deploy docker --tunnel --run", note: "Compose + a public URL" },
         { cmd: "fastagent deploy railway", note: "print the runbook only" },
+        { cmd: "fastagent deploy agentcore --run", note: "arm64 image + stack + webhooks" },
     ],
     notes: "Definition-read-only: the only writes are generated artifacts (never clobbered without " +
         "--force). A routine redeploy of an already-provisioned agent is just the host's own command " +
@@ -324,6 +400,7 @@ const deploy = {
         intoLinked: f.intoLinked === true,
         model: f.model,
         authPath: f.authPath,
+        input: f.input !== false,
     }),
 };
 const schedule = {
@@ -370,10 +447,11 @@ const schedule = {
 const login = {
     name: "login",
     summary: "authenticate a model provider (subscription/OAuth or API key)",
-    description: "Authenticate a model provider into the project-level <state root>/auth.json — default " +
-        "<cwd>/.fastagent/auth.json (run from $HOME for the global ~/.fastagent/auth.json): pick a method " +
-        "(subscription/OAuth or API key), then a provider that offers it (configured status shown). " +
-        "[provider] takes the method from what that provider supports, asked only when both.",
+    description: "Authenticate a model provider into the project-level <agent dir>/.secrets/auth.json (outside an " +
+        "agent it writes the global ~/.fastagent/.secrets/auth.json, and says so): pick a method " +
+        "(subscription/OAuth or API " +
+        "key), then a provider that offers it (configured status shown). [provider] takes the method from " +
+        "what that provider supports, asked only when both.",
     args: [{ name: "[provider]", description: "provider id (skip the provider menu)" }],
     flags: [AUTH_PATH, NO_INPUT],
     examples: [{ cmd: "fastagent login" }, { cmd: "fastagent login openai" }],
@@ -395,6 +473,7 @@ export const specs = [
     schedule,
     dev,
     chat,
+    attach,
     start,
     add,
     deploy,

package/dist/cli/serve.d.ts

@@ -1,28 +1,68 @@
-/**
- * The serving spine shared by `dev` (its worker) and `start`: route assembly from discovered
- * channels/, the Node host binding, the scheduler lifecycle, and the optional Cloudflare quick
- * tunnel. Bodies moved verbatim from cli.ts; `values.tunnel` became a parameter.
- */
 import type { Agent } from "../agent.ts";
+import { type LoadedLongConnectionChannel } from "../engines/pi/channel.ts";
 import { type Routes } from "../host/node.ts";
+import type { LoadedSchedule } from "../schedule/schedule.ts";
+import type { SessionControl } from "../session.ts";
+export interface ServingSurface {
+    routes: Routes;
+    longConnections: LoadedLongConnectionChannel[];
+    /** Route-channel basenames; the tunnel registers only this subset. */
+    routeChannels: string[];
+    builtinInvoke: boolean;
+    /** Marks the built-in health route ready after every long-connection channel first connects. */
+    markReady(): void;
+}
+/**
+ * The surface this deployment serves: default `GET /health` plus discovered channels, or the default
+ * POST `/invoke` only when neither a route nor a long-connection channel was declared.
+ */
+export declare function routesFor(agentDir: string, agent: Agent, stateRoot: string, control?: SessionControl, options?: {
+    builtinInvoke?: boolean;
+}): Promise<ServingSurface>;
+/**
+ * Mount the session control plane (`/control/*`) when the agent enabled it
+ * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
+ * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
+ * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
+ * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
+ * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
+ * (routesFor): `sessionControl` is an explicit opt-in, so declaring both is a configuration error,
+ * and silently shadowing either side would serve a surface the author didn't write.
+ */
+export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, stateRoot: string, options?: {
+    tunnel?: boolean;
+    agent?: Agent;
+}): {
+    routes: Routes;
+    announce: (boundPort: number) => void;
+};
 /**
- * The routes this deployment serves: a default `GET /health` plus the workspace's discovered
- * `channels/` — or the default invoke channel at POST /invoke when none are declared.
+ * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) over the serving routes —
+ * the deployed container's ONLY reachable surface (channels/agentcore.ts). Wired by `start` when
+ * `FASTAGENT_AGENTCORE=1` (set by the generated deploy artifacts, never by hand). A channel colliding
+ * on either path fails startup, same disposition as the control-plane mount: the adapter's paths are
+ * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
  */
-export declare function routesFor(workspaceDir: string, agent: Agent, stateRoot: string): Promise<Routes>;
-/** Serve `routes` via the Node host. serveNode owns binding; the CLI owns policy (errors, ready signal, log). */
-export declare function serve(routes: Routes, port: number, onListening?: (boundPort: number) => void): void;
+export declare function mountAgentcore(routes: Routes, options: {
+    agent: Agent;
+    stateRoot: string;
+    schedules: LoadedSchedule[];
+    onStateReady?: () => void;
+}): Routes;
 /**
- * Start a Cloudflare tunnel + announce/register webhooks once the server is bound — unless this is a
- * watch-supervisor worker, where the supervisor owns the long-lived tunnel so the public URL survives
- * reloads.
+ * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
+ * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
+ * the sole clean-shutdown command.
  */
-export declare function maybeTunnel(workspaceDir: string, boundPort: number, tunnel: boolean): void;
+export declare function serve(surface: ServingSurface, port: number, onListening?: (boundPort: number) => void): void;
+/** Start a Cloudflare tunnel for route channels only. */
+export declare function maybeTunnel(agentDir: string, routeChannels: string[], boundPort: number, tunnel: boolean, stateRoot?: string): void;
 /**
- * Load and start the workspace's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
- * there are static schedules OR `selfSchedule` is on (the scheduler also polls the agent's self-scheduled
- * wake-ups, which the built-in `wake` tool creates only when opted in). Shares the SAME (trace-wrapped)
- * agent the routes serve, so a scheduled turn is observed like any other. Best-effort stop on exit; dev's
- * watch restart re-reads schedules with the worker (schedules are a code input). Single-process.
+ * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
+ * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals. Returns the
+ * loaded schedules so a serving surface that needs them (the AgentCore adapter's fire binding) shares
+ * ONE load instead of re-discovering. `externalClock` (AgentCore) arms no resident cron timers.
  */
-export declare function startSchedules(workspaceDir: string, agent: Agent, stateRoot: string, selfSchedule: boolean): Promise<void>;
+export declare function startSchedules(agentDir: string, agent: Agent, stateRoot: string, selfSchedule: boolean, options?: {
+    externalClock?: boolean;
+}): Promise<LoadedSchedule[]>;