@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/deploy/agentcore/plan.js

@@ -1,5 +1,4 @@
 /** `fastagent deploy agentcore` — the AWS Bedrock AgentCore deploy PLAN, computed from the resolved definition. */
-import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { MAX_WEBHOOK_BODY_BYTES } from "../../channels/agentcore-limits.js";
 import { SECRETS_DIRNAME } from "../../paths.js";
@@ -28,6 +27,13 @@ export const FORWARDER_FILE = "lambda/index.js";
 export function wakeAlarmPrefix(name) {
     return `fa-${name}-wk-`;
 }
+/**
+ * Where the forwarder puts the recurring schedule for each `schedules/` file. Set at runtime by the container (the
+ * set follows edits), so like the wake alarms it is no stack resource, and this prefix is the handle on them.
+ */
+export function recurringSchedulePrefix(name) {
+    return `fa-${name}-sc-`;
+}
 /** Account-suffixed artifact bucket for S3's global namespace. */
 export function deploymentBucketName(name, account) {
     return `fa-${name}-${account}`;
@@ -56,9 +62,9 @@ export const GENERATED_TEMPLATE_MARKER = "# Generated by `fastagent deploy agent
 export function isGeneratedAgentcoreTemplate(content) {
     return content.startsWith(GENERATED_TEMPLATE_MARKER);
 }
-/** Deployment base name from the workspace basename — the ONE mapping used to find its stack later. */
-export function agentcoreName(workspaceBasename) {
-    return (workspaceBasename
+/** Deployment base name from the agent directory's name — the ONE mapping used to find its stack later. */
+export function agentcoreName(agentDirName) {
+    return (agentDirName
         .toLowerCase()
         .replace(/[^a-z0-9-]+/g, "-")
         .replace(/^-+|-+$/g, "") || "agent");
@@ -105,81 +111,12 @@ export function runtimeLogGroupPrefix(runtimeOrName) {
 export function forwarderLogGroup(name) {
     return `/aws/lambda/${forwarderFunctionName(name)}`;
 }
-/** The ONE fixed ingress session id (webhooks + routine fires). */
+/** The `invoke-agent-runtime` payload IAM may send: a probe, answered `{"ok":true}` once the definition opened. */
+export const PROBE_PAYLOAD = JSON.stringify({ kind: "probe" });
+/** The ONE fixed ingress session id (webhooks + schedule fires). */
 export function ingressSessionId(name) {
     return `fastagent-ingress-${name}`.padEnd(33, "0").slice(0, 128);
 }
-/** Remap ONE day-of-week field from standard cron numbering (0–7, 0/7 = Sunday) to EventBridge's (1–7, 1 = Sunday). */
-function mapDowField(dow) {
-    const items = [];
-    for (const item of dow.split(",")) {
-        const slash = item.split("/");
-        if (slash.length > 2 || slash.some((part) => part === "")) {
-            return { error: `malformed day-of-week token "${item}"` };
-        }
-        const [body, step] = slash;
-        if (step !== undefined && !/^\d+$/.test(step))
-            return { error: `malformed day-of-week step "${item}"` };
-        let mapped;
-        if (body === "*") {
-            mapped = "*";
-        }
-        else {
-            const endpoints = body.split("-");
-            if (endpoints.length > 2 || endpoints.some((part) => part === "")) {
-                return { error: `malformed day-of-week token "${item}"` };
-            }
-            const remapped = endpoints.map((p) => (/^\d+$/.test(p) ? String((Number(p) % 7) + 1) : p));
-            if (remapped.length === 2 &&
-                remapped.every((p) => /^\d+$/.test(p)) &&
-                Number(remapped[0]) > Number(remapped[1])) {
-                return {
-                    error: `day-of-week range "${body}" wraps across the week under EventBridge numbering (1 = Sunday) — ` +
-                        `split it into an explicit list`,
-                };
-            }
-            mapped = remapped.join("-");
-        }
-        items.push(step !== undefined ? `${mapped}/${step}` : mapped);
-    }
-    return { value: items.join(",") };
-}
-/** Translate a 5-field cron into EventBridge Scheduler's `cron(m h dom mon dow *)`, or say why it can't be. */
-export function toEventBridgeCron(cron) {
-    const fields = cron.trim().split(/\s+/);
-    if (fields.length !== 5) {
-        return { error: `EventBridge supports 5-field cron only (got ${fields.length} fields)` };
-    }
-    const [min, hour, dom, mon, dow] = fields;
-    if (/[L#]/i.test(dow) || /[L#]/i.test(dom)) {
-        return { error: "L/# day forms don't translate to EventBridge numbering — set this schedule up manually" };
-    }
-    // `?` FIRST, and not as a synonym for `*`.
-    if (dom === "?" || dow === "?") {
-        return { expression: `cron(${min} ${hour} * ${mon} ? *)` };
-    }
-    if (dom !== "*" && dow !== "*") {
-        return {
-            error: "restricting BOTH day-of-month and day-of-week (cron OR semantics) is not expressible in EventBridge",
-        };
-    }
-    if (dow === "*") {
-        return { expression: `cron(${min} ${hour} ${dom} ${mon} ? *)` };
-    }
-    const mapped = mapDowField(dow);
-    if ("error" in mapped)
-        return mapped;
-    return { expression: `cron(${min} ${hour} ? ${mon} ${mapped.value} *)` };
-}
-/** CFN logical id fragment from a schedule name (alphanumeric only, capitalized). */
-function logicalId(name) {
-    const slug = name.replace(/[^a-zA-Z0-9]+/g, "");
-    return slug.charAt(0).toUpperCase() + slug.slice(1) || "Schedule";
-}
-/** YAML single-quoted scalar (the one escape: `'` doubles). */
-function yamlSingleQuote(value) {
-    return `'${value.replace(/'/g, "''")}'`;
-}
 /**
  * The forwarder Lambda source — `forwarder.js` beside this file, the ONE text both the deployment package and the
  * readable `lambda/index.js` artifact are generated from.
@@ -187,16 +124,8 @@ function yamlSingleQuote(value) {
 export function forwarderSource() {
     return readFileSync(new URL("./forwarder.js", import.meta.url), "utf8");
 }
-/** The EventBridge physical name for a schedule. */
-export function scheduleResourceName(agent, schedule) {
-    const prefix = `fa-${agent}-`;
-    const hash = createHash("sha256").update(schedule).digest("hex").slice(0, 8);
-    const safe = schedule.replace(/[^0-9A-Za-z\-_.]+/g, "-").replace(/^-+|-+$/g, "");
-    const room = Math.max(0, 64 - prefix.length - hash.length - 1);
-    return `${prefix}${safe.slice(0, room)}-${hash}`;
-}
 /** The CloudFormation template — the whole topology in one stack. */
-function template(input, translated, topology) {
+function template(input, topology) {
     const runtimeName = toRuntimeName(input.name);
     const idleTimeout = input.idleTimeoutSeconds ?? DEFAULT_IDLE_TIMEOUT_SECONDS;
     const forwarderFnArn = `!Sub arn:aws:lambda:\${AWS::Region}:\${AWS::AccountId}:function:fastagent-${input.name}-forwarder`;
@@ -296,17 +225,9 @@ function template(input, translated, topology) {
         `      EnvironmentVariables:`,
         ...envLines,
     ];
-    lines.push(``, `  ForwarderRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: lambda.amazonaws.com }`, `            Action: sts:AssumeRole`, `      ManagedPolicyArns: [arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole]`, `      Policies:`, `        - PolicyName: invoke-runtime`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: bedrock-agentcore:InvokeAgentRuntime`, `                Resource:`, `                  - !GetAtt Runtime.AgentRuntimeArn`, `                  - !Sub "\${Runtime.AgentRuntimeArn}/*"`, `              - Effect: Allow # wake alarms: mirror pending wake-ups into one-shot schedules`, `                Action: [scheduler:CreateSchedule, scheduler:UpdateSchedule]`, `                Resource: !Sub arn:aws:scheduler:\${AWS::Region}:\${AWS::AccountId}:schedule/default/${wakeAlarmPrefix(input.name)}*`, `              - Effect: Allow # hand the poke schedules their invoke role`, `                Action: iam:PassRole`, `                Resource: !GetAtt WakeSchedulerRole.Arn`, `              - Effect: Allow # self-resolve callback URL for state-URL refresh / wake alarms`, `                Action: lambda:GetFunctionUrlConfig`, `                Resource: ${forwarderFnArn}`, ``, `  Forwarder:`, `    Type: AWS::Lambda::Function`, `    Properties:`, `      FunctionName: ${forwarderFunctionName(input.name)}`, `      Runtime: nodejs22.x`, `      Handler: index.handler`, `      # Webhook ACKs are fast, but routine-fire holds the connection for the WHOLE agent turn`, `      # (claim-before-run means a timeout never double-fires; the turn also continues and is`, `      # audited container-side). EventBridge→Lambda is async, so the long timeout costs nothing.`, `      Timeout: 900`, `      MemorySize: 256`, `      Role: !GetAtt ForwarderRole.Arn`, `      Environment:`, `        Variables:`, `          RUNTIME_ARN: !GetAtt Runtime.AgentRuntimeArn`, `          INGRESS_SESSION_ID: ${ingressSessionId(input.name)}`, ...(topology.webhooks ? [`          WEBHOOKS_ENABLED: "1"`] : []), `          WAKE_SECRET: !Ref FastagentWakeSecret`, `          WAKE_ROLE_ARN: !GetAtt WakeSchedulerRole.Arn`, `          WAKE_PREFIX: ${wakeAlarmPrefix(input.name)}`, `          INGRESS_SECRET: !Ref FastagentIngressSecret`, `          MAX_WEBHOOK_BODY_BYTES: "${MAX_WEBHOOK_BODY_BYTES}"`, `      # A content-hashed key makes code changes visible to CloudFormation.`, `      Code:`, `        S3Bucket: !Ref ForwarderBucket`, `        S3Key: !Ref ForwarderS3Key`);
+    lines.push(``, `  ForwarderRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: lambda.amazonaws.com }`, `            Action: sts:AssumeRole`, `      ManagedPolicyArns: [arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole]`, `      Policies:`, `        - PolicyName: invoke-runtime`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: bedrock-agentcore:InvokeAgentRuntime`, `                Resource:`, `                  - !GetAtt Runtime.AgentRuntimeArn`, `                  - !Sub "\${Runtime.AgentRuntimeArn}/*"`, `              - Effect: Allow # wake alarms: mirror pending wake-ups into one-shot schedules`, `                Action: [scheduler:CreateSchedule, scheduler:UpdateSchedule]`, `                Resource: !Sub arn:aws:scheduler:\${AWS::Region}:\${AWS::AccountId}:schedule/default/${wakeAlarmPrefix(input.name)}*`, `              - Effect: Allow # schedules: one recurring schedule per schedules/ file, and delete what is gone`, `                Action: [scheduler:CreateSchedule, scheduler:UpdateSchedule, scheduler:GetSchedule, scheduler:DeleteSchedule]`, `                Resource: !Sub arn:aws:scheduler:\${AWS::Region}:\${AWS::AccountId}:schedule/default/${recurringSchedulePrefix(input.name)}*`, `              - Effect: Allow # find the recurring schedules to delete (ListSchedules takes no resource)`, `                Action: scheduler:ListSchedules`, `                Resource: "*"`, `              - Effect: Allow # hand the alarm schedules their invoke role`, `                Action: iam:PassRole`, `                Resource: !GetAtt WakeSchedulerRole.Arn`, `              - Effect: Allow # self-resolve callback URL for state-URL refresh / wake alarms`, `                Action: lambda:GetFunctionUrlConfig`, `                Resource: ${forwarderFnArn}`, ``, `  Forwarder:`, `    Type: AWS::Lambda::Function`, `    Properties:`, `      FunctionName: ${forwarderFunctionName(input.name)}`, `      Runtime: nodejs22.x`, `      Handler: index.handler`, `      # Webhook ACKs are fast, but schedule-fire holds the connection for the WHOLE agent turn`, `      # (claim-before-run means a timeout never double-fires; the turn also continues and is`, `      # audited container-side). EventBridge→Lambda is async, so the long timeout costs nothing.`, `      Timeout: 900`, `      MemorySize: 256`, `      Role: !GetAtt ForwarderRole.Arn`, `      Environment:`, `        Variables:`, `          RUNTIME_ARN: !GetAtt Runtime.AgentRuntimeArn`, `          INGRESS_SESSION_ID: ${ingressSessionId(input.name)}`, ...(topology.webhooks ? [`          WEBHOOKS_ENABLED: "1"`] : []), `          WAKE_SECRET: !Ref FastagentWakeSecret`, `          WAKE_ROLE_ARN: !GetAtt WakeSchedulerRole.Arn`, `          WAKE_PREFIX: ${wakeAlarmPrefix(input.name)}`, `          SCHEDULE_PREFIX: ${recurringSchedulePrefix(input.name)}`, `          INGRESS_SECRET: !Ref FastagentIngressSecret`, `          MAX_WEBHOOK_BODY_BYTES: "${MAX_WEBHOOK_BODY_BYTES}"`, `      # A content-hashed key makes code changes visible to CloudFormation.`, `      Code:`, `        S3Bucket: !Ref ForwarderBucket`, `        S3Key: !Ref ForwarderS3Key`);
     lines.push(``, `  ForwarderUrl:`, `    Type: AWS::Lambda::Url`, `    Properties:`, `      TargetFunctionArn: !GetAtt Forwarder.Arn`, `      # NONE is deliberate: webhook callers (Telegram/Feishu) cannot SigV4-sign. Authenticity is`, `      # verified downstream by each channel (secret token / signature), exactly as on every host.`, `      AuthType: NONE`, ``, `  ForwarderUrlPermission:`, `    Type: AWS::Lambda::Permission`, `    Properties:`, `      FunctionName: !Ref Forwarder`, `      Action: lambda:InvokeFunctionUrl`, `      Principal: "*"`, `      FunctionUrlAuthType: NONE`, ``, `  # Function URLs created after Oct 2025 require lambda:InvokeFunction IN ADDITION to`, `  # lambda:InvokeFunctionUrl for public (NONE) access — with only the first, every request 403s`, `  # (found by the first real deploy). InvokedViaFunctionUrl scopes it to URL traffic: without it`, `  # the bare * principal would also let any AWS principal call the Lambda API directly, bypassing`, `  # the Function URL event shape to forge internal events.`, `  ForwarderInvokePermission:`, `    Type: AWS::Lambda::Permission`, `    Properties:`, `      FunctionName: !Ref Forwarder`, `      Action: lambda:InvokeFunction`, `      Principal: "*"`, `      InvokedViaFunctionUrl: true`);
-    lines.push(``, `  # The role the wake-poke schedules assume to invoke the forwarder. Its policy names the`, `  # function by CONSTRUCTED arn (not !Ref) — the forwarder's env references this role, so a`, `  # !Ref back would be a circular dependency.`, `  WakeSchedulerRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: scheduler.amazonaws.com }`, `            Action: sts:AssumeRole`, `            Condition:`, `              StringEquals: { aws:SourceAccount: !Ref AWS::AccountId }`, `      Policies:`, `        - PolicyName: poke-forwarder`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: lambda:InvokeFunction`, `                Resource: ${forwarderFnArn}`);
-    if (translated.length > 0) {
-        lines.push(``, `  SchedulerRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: scheduler.amazonaws.com }`, `            Action: sts:AssumeRole`, `            Condition:`, `              StringEquals: { aws:SourceAccount: !Ref AWS::AccountId }`, `      Policies:`, `        - PolicyName: fire-forwarder`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: lambda:InvokeFunction`, `                Resource: !GetAtt Forwarder.Arn`);
-        for (const { fact, expression } of translated) {
-            lines.push(``, `  Schedule${logicalId(fact.name)}:`, `    Type: AWS::Scheduler::Schedule`, `    Properties:`, `      Name: ${scheduleResourceName(input.name, fact.name)}`, `      ScheduleExpression: ${expression}`, `      ScheduleExpressionTimezone: ${fact.tz ?? "Etc/UTC"}`, `      FlexibleTimeWindow: { Mode: "OFF" }`, `      Target:`, `        Arn: !GetAtt Forwarder.Arn`, `        RoleArn: !GetAtt SchedulerRole.Arn`, `        # <aws.scheduler.scheduled-time> is the clock's NAME for this occurrence: EventBridge repeats it`, `        # byte-identical on every redelivery, which is what makes the container's dedup work.`, `        Input: ${yamlSingleQuote(JSON.stringify({
-                scheduleFire: { name: fact.name, occurrence: "<aws.scheduler.scheduled-time>" },
-            }))}`);
-        }
-    }
+    lines.push(``, `  # The role the alarm schedules (wake pokes and schedule fires) assume to invoke the forwarder. Its policy names the`, `  # function by CONSTRUCTED arn (not !Ref) — the forwarder's env references this role, so a`, `  # !Ref back would be a circular dependency.`, `  WakeSchedulerRole:`, `    Type: AWS::IAM::Role`, `    Properties:`, `      AssumeRolePolicyDocument:`, `        Version: "2012-10-17"`, `        Statement:`, `          - Effect: Allow`, `            Principal: { Service: scheduler.amazonaws.com }`, `            Action: sts:AssumeRole`, `            Condition:`, `              StringEquals: { aws:SourceAccount: !Ref AWS::AccountId }`, `      Policies:`, `        - PolicyName: poke-forwarder`, `          PolicyDocument:`, `            Version: "2012-10-17"`, `            Statement:`, `              - Effect: Allow`, `                Action: lambda:InvokeFunction`, `                Resource: ${forwarderFnArn}`);
     lines.push(``, `Outputs:`, `  RuntimeArn:`, `    Value: !GetAtt Runtime.AgentRuntimeArn`);
     lines.push(`  ForwarderUrl:`, `    Value: !GetAtt ForwarderUrl.FunctionUrl`);
     return `${lines.join("\n")}\n`;
@@ -316,40 +237,17 @@ export function planAgentcoreDeploy(input) {
     const { name, channels } = input;
     const stack = agentcoreStackName(name);
     const repo = agentcoreRepoName(name);
-    const prefix = input.agentPrefix;
-    // Translate every schedule; the ones EventBridge cannot express become explicit runbook warnings.
-    const translated = [];
-    const untranslatable = [];
-    for (const fact of input.schedules) {
-        const result = toEventBridgeCron(fact.cron);
-        if ("expression" in result)
-            translated.push({ fact, expression: result.expression });
-        else
-            untranslatable.push({ name: fact.name, reason: result.error });
-    }
-    // Identifier collisions: the author-side → AWS-side name mappings are lossy (logical ids strip punctuation;
-    // parameter names collapse underscores), so two DISTINCT legal inputs can land on one CloudFormation key — which
-    // would generate a silently wrong stack.
-    const logicalIds = new Map();
-    for (const { fact } of translated) {
-        const id = `Schedule${logicalId(fact.name)}`;
-        const clash = logicalIds.get(id);
-        if (clash !== undefined) {
-            throw new Error(`schedules "${clash}" and "${fact.name}" collapse to the same CloudFormation logical id (${id}) — rename one`);
-        }
-        logicalIds.set(id, fact.name);
-    }
     const topology = agentcoreTopology(input);
     const artifacts = [
-        { path: `${prefix}${TEMPLATE_FILE}`, content: template(input, translated, topology) },
-        { path: `${prefix}${FORWARDER_FILE}`, content: forwarderSource() },
+        { path: TEMPLATE_FILE, content: template(input, topology) },
+        { path: FORWARDER_FILE, content: forwarderSource() },
         ...containerArtifacts(input),
     ];
     const secrets = input.secrets ?? [];
     const image = `<account-id>.dkr.ecr.<region>.amazonaws.com/${repo}:<tag>`;
     const bucketHint = deploymentBucketName(name, "<account-id>");
     const runbook = [
-        `# Deploy "${name}" to AWS Bedrock AgentCore. ${prefix}${TEMPLATE_FILE} / Dockerfile(.dockerignore) are generated above.`,
+        `# Deploy "${name}" to AWS Bedrock AgentCore. ${TEMPLATE_FILE} / Dockerfile(.dockerignore) are generated above.`,
         `# Prereqs: AWS CLI v2 with credentials + a region where AgentCore is available, and Docker with buildx`,
         `# (the image MUST be linux/arm64 — the one host whose build runs on YOUR machine, not remotely).`,
         ``,
@@ -363,24 +261,25 @@ export function planAgentcoreDeploy(input) {
         ``,
         `# 1b. Package the forwarder and upload it. Name the object by its CONTENT (a hash/date):`,
         `#     CloudFormation rolls the function only when the ForwarderS3Key VALUE changes.`,
-        `(cd ${prefix}lambda && zip -q forwarder.zip index.js)`,
-        `aws s3 cp ${prefix}lambda/forwarder.zip s3://${bucketHint}/forwarder/<hash>.zip`,
+        `(cd lambda && zip -q forwarder.zip index.js)`,
+        `aws s3 cp lambda/forwarder.zip s3://${bucketHint}/forwarder/<hash>.zip`,
         ``,
         `# 2. Build (linux/arm64) + push. Use a UNIQUE tag per deploy (a git sha / date): CloudFormation only`,
         `#    rolls the runtime when the ImageUri VALUE changes — re-pushing the same tag deploys nothing.`,
         `aws ecr get-login-password | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com`,
-        `docker buildx build --platform linux/arm64 -f ${prefix}Dockerfile -t ${image} --push .`,
+        `docker buildx build --platform linux/arm64 -f Dockerfile -t ${image} --push .`,
         ``,
-        `# 3. Deploy the stack (runtime + ingress + schedules in one template).`,
+        `# 3. Deploy the stack (runtime + ingress in one template).`,
     ];
     if (secrets.length > 0) {
         runbook.push(`#    Variables ride ONE NoEcho parameter, FastagentEnv: base64 of a JSON object {"NAME": "value", …},`, `#    split every ${CARRIER_CHUNK_SIZE} chars across FastagentEnv, FastagentEnv2 … (\`--run\` builds it):`, ...secrets.map((s) => `#      ${s.name}: ${s.hint}`));
     }
-    const wakeSecretHint = " FastagentWakeSecret=<any random string>";
+    const wakeSecretHint = " FastagentWakeSecret=<any random string> FastagentIngressSecret=<another random string>";
     runbook.push(`#      FastagentWakeSecret: the wake-alarm shared secret — any random string (\`--run\` mints one)`);
-    runbook.push(`aws cloudformation deploy --stack-name ${stack} --template-file ${prefix}${TEMPLATE_FILE} \\`, `  --capabilities CAPABILITY_IAM \\`, `  --parameter-overrides ImageUri=${image} ForwarderBucket=${bucketHint} ForwarderS3Key=forwarder/<hash>.zip${secrets.length > 0 ? " FastagentEnv=<base64 JSON>" : ""}${wakeSecretHint}`, ``, `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`, `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery resolves the per-endpoint log group from the stack's RuntimeArn:`, `fastagent logs agentcore --follow`, `# The ingress transport is a separate Lambda and therefore a separate log source:`, `fastagent logs agentcore --source forwarder --follow`, ``, `# 6. Set a log retention period on EVERY group this stack writes to. Each is created by the service that`, `#    writes it, not by this template, and CloudWatch keeps log data indefinitely by default — which is`, `#    forever-billed storage, and the logs are where WHY a scheduled turn failed is recorded. Logs are the`, `#    ONE state path this host does not reclaim on its own.`, `aws logs put-retention-policy --log-group-name <the group \`fastagent logs agentcore\` resolves> --retention-in-days 14`, `# The forwarder is a separate Lambda, so its group is separate and defaults the same way:`, `aws logs put-retention-policy --log-group-name ${forwarderLogGroup(input.name)} --retention-in-days 14`);
+    runbook.push(`#      FastagentIngressSecret: what proves an envelope came from the forwarder — another random string, kept for the activation below`);
+    runbook.push(`aws cloudformation deploy --stack-name ${stack} --template-file ${TEMPLATE_FILE} \\`, `  --capabilities CAPABILITY_IAM \\`, `  --parameter-overrides ImageUri=${image} ForwarderBucket=${bucketHint} ForwarderS3Key=forwarder/<hash>.zip${secrets.length > 0 ? " FastagentEnv=<base64 JSON>" : ""}${wakeSecretHint}`, ``, `# 4. Read the outputs (the runtime ARN + callback URL; it serves webhooks only when configured):`, `aws cloudformation describe-stacks --stack-name ${stack} --query "Stacks[0].Outputs"`, ``, `# 5. Tail the Runtime's application stdout/stderr (same fastagent messages + log level as locally).`, `#    Discovery resolves the per-endpoint log group from the stack's RuntimeArn:`, `fastagent logs agentcore --follow`, `# The ingress transport is a separate Lambda and therefore a separate log source:`, `fastagent logs agentcore --source forwarder --follow`, ``, `# 6. Set a log retention period on EVERY group this stack writes to. Each is created by the service that`, `#    writes it, not by this template, and CloudWatch keeps log data indefinitely by default — which is`, `#    forever-billed storage, and the logs are where WHY a scheduled turn failed is recorded. Logs are the`, `#    ONE state path this host does not reclaim on its own.`, `aws logs put-retention-policy --log-group-name <the group \`fastagent logs agentcore\` resolves> --retention-in-days 14`, `# The forwarder is a separate Lambda, so its group is separate and defaults the same way:`, `aws logs put-retention-policy --log-group-name ${forwarderLogGroup(input.name)} --retention-in-days 14`);
     if (input.boxLogin) {
-        runbook.push(``, `# Model auth: after EVERY deploy and after 14 idle days (each storage reset wipes the last login),`, `# log the runtime in to ${input.boxLogin} from this workspace — before pointing any webhook at it:`, `${deploymentLoginCommand("agentcore", input.boxLogin)}`);
+        runbook.push(``, `# Model auth: after EVERY deploy and after 14 idle days (each storage reset wipes the last login),`, `# log the runtime in to ${input.boxLogin} from the agent directory — before pointing any webhook at it:`, `${deploymentLoginCommand("agentcore", input.boxLogin)}`);
     }
     // Post-deploy webhook registration — the shared channel-ingress steps, pointed at the forwarder's Function URL
     // (read from the stack outputs).
@@ -392,11 +291,8 @@ export function planAgentcoreDeploy(input) {
     }
     if (post.length > 0)
         runbook.push(``, ...post);
-    for (const u of untranslatable) {
-        runbook.push(``, `# WARNING: schedule "${u.name}" has NO EventBridge rule — ${u.reason}.`, `#   It will NOT fire on this deployment until you create an equivalent trigger yourself.`);
-    }
-    runbook.push(``, `# Wake-ups: the agent's own follow-up turns (the wake tool) are EventBridge-backed — each pending wake-up is mirrored`, `#   (via the forwarder, authenticated by FastagentWakeSecret) into a self-deleting one-shot`, `#   schedule (fa-${name}-wk-*) that wakes the container at the right instant. Reliable even when`, `#   the compute is reclaimed. The forwarder supplies the callback URL; use the deployment's`, `#   fixed runtime session id for programmatic calls too.`);
-    runbook.push(``, `# Invoke the agent programmatically (reuse the deployment session; conversations remain separate):`, `aws bedrock-agentcore invoke-agent-runtime --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}" \\`, `  --payload '{"kind":"invoke","session":"cli","text":"hello"}' --cli-binary-format raw-in-base64-out /dev/stdout`);
-    runbook.push(``, `# Stop the fixed runtime session after redeploy so the next call uses the new image.`, `# \`--run\` does this automatically. In-flight turns are interrupted.`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`, ``, `# Redeploy = \`fastagent deploy agentcore\` (a new definition needs a fresh release manifest) + step 1b`, `# (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is managed SessionStorage. It keeps base/ (including unfinished work), .state/`, `# and .secrets/ across compute stop/resume — an idle-reclaimed agent resumes with its memory. AWS`, `# RESETS it on every runtime version update (i.e. every deploy) and after 14 idle days, so a deploy`, `# replaces the state along with the image: sessions, channel state and pending wake-ups start blank.`, `# A provider API key in the value file travels with every deploy; a login on the runtime survives neither reset.`, `# Cross-deploy memory needs EFS or S3 Files, which are VPC-only (a NAT gateway for model/channel`, `# egress, ~$33/mo standing): use \`deploy fly\` or \`deploy railway\` for a real volume instead.`, `# Keep one runtime writer per workspace; use the fixed runtime session id printed above for every entry point.`);
-    return { artifacts, runbook, untranslatableSchedules: untranslatable, topology };
+    runbook.push(``, `# Schedules and wake-ups are EventBridge-backed: the container mirrors (via the forwarder, authenticated by`, `#   FastagentWakeSecret) each schedule into a recurring EventBridge schedule (${recurringSchedulePrefix(name)}*) and each pending`, `#   wake-up into a self-deleting one-shot (${wakeAlarmPrefix(name)}*), which wake it even when the compute is reclaimed.`, `#   So a schedule written or edited on the runtime takes effect without a deploy. The container sets them only`, `#   once an envelope has reached it THROUGH THE FORWARDER, which tells it where the forwarder is; an`, `#   invoke-agent-runtime call does not (that door is IAM's, and does not carry it). \`--run\` does this with its`, `#   probe. After a manual deploy, do it once, or no schedule fires until a webhook arrives:`, `curl -fsS -X POST "<ForwarderUrl>/__fastagent/probe" -d '{"auth":"<FastagentIngressSecret>"}'`);
+    runbook.push(``, `# Check that the deployed agent opens ({"ok":true}); it is reached through its channels, not this call:`, `aws bedrock-agentcore invoke-agent-runtime --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}" \\`, `  --payload '${PROBE_PAYLOAD}' --cli-binary-format raw-in-base64-out /dev/stdout`);
+    runbook.push(``, `# Stop the fixed runtime session after redeploy so the next call uses the new image.`, `# \`--run\` does this automatically. In-flight turns are interrupted.`, `aws bedrock-agentcore stop-runtime-session --agent-runtime-arn <RuntimeArn> \\`, `  --runtime-session-id "${ingressSessionId(name)}"`, ``, `# Redeploy = \`fastagent deploy agentcore\` (a new definition needs a fresh release manifest) + step 1b`, `# (new forwarder key, if its code changed) + step 2 with a NEW tag + step 3.`, `# STATE: ${MOUNT} is managed SessionStorage. It keeps definition/ (with what the agent wrote there), .state/`, `# and .secrets/ across compute stop/resume — an idle-reclaimed agent resumes with its memory. AWS`, `# RESETS it on every runtime version update (i.e. every deploy) and after 14 idle days, so a deploy`, `# replaces the state along with the image: sessions, channel state and pending wake-ups start blank.`, `# A provider API key in the value file travels with every deploy; a login on the runtime survives neither reset.`, `# Cross-deploy memory needs EFS or S3 Files, which are VPC-only (a NAT gateway for model/channel`, `# egress, ~$33/mo standing): use \`deploy fly\` or \`deploy railway\` for a real volume instead.`, `# Keep one runtime writer per agent; use the fixed runtime session id printed above for every entry point.`);
+    return { artifacts, runbook, topology };
 }

package/dist/deploy/agentcore/run.d.ts

@@ -22,7 +22,7 @@ export interface AgentcoreRunPlan {
     secrets: Record<string, string>;
     /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
     missingSecrets: string[];
-    /** That value file, workspace-relative, so the gate names the file this deploy actually read. */
+    /** That value file, agent-dir-relative, so the gate names the file this deploy actually read. */
     valueFile: string;
     /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
     channels: readonly DeclaredChannel[];

package/dist/deploy/agentcore/run.js

@@ -6,6 +6,8 @@ import { Buffer } from "node:buffer";
 import { CARRIERS, CARRIER_CHUNK_SIZE, CARRIER_MAX_CHUNKS, MOUNT, agentcoreRepoName, agentcoreStackName, carrierChunk, deploymentBucketName, forwarderSource, ingressSessionId, } from "./plan.js";
 import { zipSingleFile } from "./zip.js";
 import { encodeCarriedEnv, missingValuesGate } from "../secrets.js";
+/** AWS keys are typed, so a coding agent's user signs the CLI in at a terminal of their own. */
+const AWS_SIGN_IN = "run `aws configure` (or `aws sso login`) in a terminal of your own, where the keys are typed, then re-run";
 /**
  * Stack statuses that hold NO agent memory: a create that never succeeded, its rollback, a change set never
  * executed, or a stack already gone. Everything else — including `UPDATE_ROLLBACK_COMPLETE` and any status AWS adds
@@ -135,11 +137,11 @@ probe = {}) {
     }));
     if (!("ok" in identity)) {
         if ("absent" in identity)
-            return gate("`aws sts get-caller-identity` found no caller — run `aws configure`");
+            return gate(`\`aws sts get-caller-identity\` found no caller — ${AWS_SIGN_IN}`);
         if (identity.code === 127)
             return gate(`${identity.unreadable}, then re-run`);
         // QUOTED: expired token, a missing profile and a proxy that eats STS are three different next actions.
-        return gate(`no working AWS credentials (${identity.unreadable}) — run \`aws configure\`, then re-run`);
+        return gate(`no working AWS credentials (${identity.unreadable}) — ${AWS_SIGN_IN}`);
     }
     const { account, principal } = identity.ok;
     let region = plan.region;
@@ -297,7 +299,8 @@ probe = {}) {
     }
     // 6. Build (linux/arm64) + push in one step.
     log(`building + pushing ${image} (linux/arm64)…`);
-    const buildArgs = ["buildx", "build", "--platform", "linux/arm64", "-t", image, "--push"];
+    // `--pull`: the base image is a floating tag, and a copy cached here may be older than the runtime floor.
+    const buildArgs = ["buildx", "build", "--pull", "--platform", "linux/arm64", "-t", image, "--push"];
     buildArgs.push("-f", plan.dockerfilePath);
     buildArgs.push(".");
     if ((await docker(buildArgs)).code !== 0) {
@@ -382,11 +385,11 @@ probe = {}) {
     }
     // Verify storage initialization and channel construction before registering webhooks.
     if (url) {
-        log("probing the deployed runtime (workspace initialization + channel construction)…");
+        log("probing the deployed runtime (storage initialization + channel construction)…");
         const verdict = await probeRuntime(`${url}${RESERVED_PATHS.probe}`, plan.secrets.FASTAGENT_INGRESS_SECRET ?? "", probe.fetchImpl ?? fetch, probe.timeoutMs, probe.intervalMs);
         if (!verdict.ok)
             return gate(verdict.gate);
-        log("runtime verified (workspace ready, channels constructed)");
+        log("runtime verified (storage ready, channels constructed)");
     }
     const notLoggedIn = await plan.boxLogin?.run(runtimeArn);
     if (notLoggedIn) {

package/dist/deploy/agentcore/shell.d.ts

@@ -19,7 +19,7 @@ export declare function shellExit(status: string): string | undefined;
 export declare function openShellChannel(url: string, command: string): BoxChannel;
 /**
  * The shell `login --deployment` opens on an AgentCore runtime, on the session its server runs in. `wake` first sends
- * that session an IAM `probe`: the runtime prepares its workspace only on an invocation, and after a deploy or an idle
+ * that session an IAM `probe`: the runtime prepares its storage only on an invocation, and after a deploy or an idle
  * reset nothing may have invoked it yet, which would leave the login no agent directory to run in.
  */
 export declare function agentcoreShell(runtimeArn: string, sessionId: string, aws: CliRunner): BoxShell;

package/dist/deploy/agentcore/shell.js

@@ -21,7 +21,7 @@ import { PassThrough, Writable } from "node:stream";
 import { SignatureV4 } from "@smithy/signature-v4";
 import { WebSocket, ping } from "undici";
 import { awsCli, awsJson } from "./aws-cli.js";
-import { MOUNT } from "./plan.js";
+import { MOUNT, PROBE_PAYLOAD } from "./plan.js";
 const STDIN = 0x00;
 const STDOUT = 0x01;
 const STDERR = 0x02;
@@ -167,7 +167,7 @@ export function openShellChannel(url, command) {
 }
 /**
  * The shell `login --deployment` opens on an AgentCore runtime, on the session its server runs in. `wake` first sends
- * that session an IAM `probe`: the runtime prepares its workspace only on an invocation, and after a deploy or an idle
+ * that session an IAM `probe`: the runtime prepares its storage only on an invocation, and after a deploy or an idle
  * reset nothing may have invoked it yet, which would leave the login no agent directory to run in.
  */
 export function agentcoreShell(runtimeArn, sessionId, aws) {
@@ -178,16 +178,16 @@ export function agentcoreShell(runtimeArn, sessionId, aws) {
             try {
                 const reply = join(dir, "reply.json");
                 const args = ["bedrock-agentcore", "invoke-agent-runtime", "--agent-runtime-arn", runtimeArn];
-                args.push("--runtime-session-id", sessionId, "--payload", '{"kind":"probe"}');
+                args.push("--runtime-session-id", sessionId, "--payload", PROBE_PAYLOAD);
                 args.push("--cli-binary-format", "raw-in-base64-out", reply);
                 const sent = await awsCli(aws).present(args);
                 if (!("ok" in sent)) {
                     const why = "absent" in sent ? "the runtime is not there" : sent.unreadable;
-                    throw new Error(`could not open the AgentCore runtime's workspace (${why})`);
+                    throw new Error(`could not open the AgentCore runtime's storage (${why})`);
                 }
                 const answer = await readFile(reply, "utf8");
                 if (!/"ok"\s*:\s*true/.test(answer)) {
-                    throw new Error(`the AgentCore runtime did not open its workspace: ${answer.trim().slice(0, 300)}`);
+                    throw new Error(`the AgentCore runtime did not open its storage: ${answer.trim().slice(0, 300)}`);
                 }
             }
             finally {

package/dist/deploy/api.d.ts

@@ -0,0 +1,34 @@
+import type { AgentConfig } from "../harnesses/pi-durable/define.ts";
+/** Whether the deployment serves the API (and whether this deploy gives it its key), and why not when it does not. */
+export type DeploymentApi = {
+    served: true;
+    generatesKey: boolean;
+} | {
+    served: false;
+    why: string;
+};
+/**
+ * Decide the API for one deploy, writing nothing: a deploy the pre-flight refuses leaves the value file as it was.
+ * Turned off, it is off on the deployment too, a key the values or the host still hold included: the serve reads the
+ * same setting.
+ */
+export declare function deploymentApi(input: {
+    config: AgentConfig;
+    /** The host serves the API at all: not AgentCore, reached only through `/invocations`. */
+    hostServes: boolean;
+    values: ReadonlyMap<string, string>;
+}): DeploymentApi;
+/**
+ * Give the deployment its key: into the value file, from which it travels with the other values, once the pre-flight
+ * passes (a host's own check may still stop this deploy; the key stays for the next). Answers a secrets directory it
+ * wrote into that git may track.
+ */
+export declare function writeApiKey(agentDir: string): Promise<string | undefined>;
+/**
+ * What a deploy says of the API, once the host has said where the deployment is reached (when it knows). The check
+ * names the agent's directory when the command runs elsewhere, since that is where `invoke --url` finds the key.
+ */
+export declare function apiReport(api: DeploymentApi, where: {
+    valueFile: string;
+    agentArg: string | undefined;
+}, reachedAt: string | undefined): string[];

package/dist/deploy/api.js

@@ -0,0 +1,50 @@
+/**
+ * A deployment's Agent API (SPEC.md §9.5, §9.6): served under `/v1` on every host but AgentCore, unless the
+ * definition turns it off (`http.api: false`), behind a key `deploy` generates into the value file the first time,
+ * which then travels with every other value. And what a deploy reports of it.
+ */
+import { randomBytes } from "node:crypto";
+import { API_PREFIX } from "../http/contract.js";
+import { API_KEY_VARIABLE, API_TURNED_OFF, apiKeysFrom, apiTurnedOff } from "../http/server.js";
+import { writeValues } from "../value-file.js";
+/**
+ * Decide the API for one deploy, writing nothing: a deploy the pre-flight refuses leaves the value file as it was.
+ * Turned off, it is off on the deployment too, a key the values or the host still hold included: the serve reads the
+ * same setting.
+ */
+export function deploymentApi(input) {
+    const { config, hostServes, values } = input;
+    if (!hostServes)
+        return { served: false, why: "this host reaches the agent only through its own invocations" };
+    if (apiTurnedOff(config))
+        return { served: false, why: API_TURNED_OFF };
+    return { served: true, generatesKey: apiKeysFrom(values.get(API_KEY_VARIABLE)).length === 0 };
+}
+/**
+ * Give the deployment its key: into the value file, from which it travels with the other values, once the pre-flight
+ * passes (a host's own check may still stop this deploy; the key stays for the next). Answers a secrets directory it
+ * wrote into that git may track.
+ */
+export async function writeApiKey(agentDir) {
+    const key = randomBytes(32).toString("base64url");
+    // Named in `overwrite`: a line that holds no key (empty, or only commas) is replaced, not kept as set.
+    const { unprotectedSecretsDir } = await writeValues(agentDir, "Agent API", [{ name: API_KEY_VARIABLE, value: key }], [API_KEY_VARIABLE]);
+    return unprotectedSecretsDir;
+}
+/**
+ * What a deploy says of the API, once the host has said where the deployment is reached (when it knows). The check
+ * names the agent's directory when the command runs elsewhere, since that is where `invoke --url` finds the key.
+ */
+export function apiReport(api, where, reachedAt) {
+    if (!api.served)
+        return [`Agent API: not served — ${api.why}`];
+    const { valueFile, agentArg } = where;
+    const base = reachedAt ?? "<the deployment's URL>";
+    return [
+        ...(api.generatesKey
+            ? [`Agent API: generated ${API_KEY_VARIABLE} in ${valueFile}; it travels with the other values`]
+            : []),
+        `Agent API: ${base}${API_PREFIX}, behind ${API_KEY_VARIABLE} in ${valueFile}`,
+        `check it: fastagent invoke --url ${base} "hello"${agentArg === undefined ? "" : ` ${agentArg}`}`,
+    ];
+}

package/dist/deploy/box-shell.d.ts

@@ -27,6 +27,12 @@ export interface BoxShell {
 }
 /** A host CLI that runs a command on the box itself: `bin ...args(command)`, run from `cwd`. */
 export declare function processShell(bin: string, args: (command: string) => string[], cwd: string): BoxShell;
+/**
+ * Why a box's login cannot be driven from here: the fastagent the agent installed on the box is older than the CLI
+ * relaying it, and speaks less of `login --stdio` than this CLI does. Fixed by versions, never by a compatibility path.
+ * No quote of either kind: it rides inside the box's shell line, which a host may wrap in single quotes.
+ */
+export declare const BOX_CLI_PREDATES: string;
 /**
  * The command that logs a deployment in, as every message and runbook names it: with the provider when it is known,
  * because the model needs THAT one, and a menu invites another.

package/dist/deploy/box-shell.js

@@ -19,6 +19,13 @@ export function processShell(bin, args, cwd) {
         },
     };
 }
+/**
+ * Why a box's login cannot be driven from here: the fastagent the agent installed on the box is older than the CLI
+ * relaying it, and speaks less of `login --stdio` than this CLI does. Fixed by versions, never by a compatibility path.
+ * No quote of either kind: it rides inside the box's shell line, which a host may wrap in single quotes.
+ */
+export const BOX_CLI_PREDATES = "the fastagent installed in the agent on the box predates the login --stdio this CLI speaks: align the " +
+    "@fastagent-sh/fastagent version in the agent package.json with the CLI that deploys it, then redeploy";
 /**
  * The command that logs a deployment in, as every message and runbook names it: with the provider when it is known,
  * because the model needs THAT one, and a menu invites another.

package/dist/deploy/build-context.d.ts

@@ -1,5 +1,5 @@
 import type { DeployReport } from "./preflight.ts";
-/** Workspace-relative paths the build context may hold and the image must not. */
+/** Agent-dir-relative paths the build context may hold and the image must not. */
 export interface BuildContextPaths {
     /** The resolved machinery dirs the generated ignore excludes by path (ContainerInput.machineryPaths). */
     machineryPaths: string[];
@@ -7,15 +7,17 @@ export interface BuildContextPaths {
     leakCandidates: string[];
     /** The state root, when it exists inside the context. */
     stateShips?: string;
-    /** The node_modules dirs that exist, the agent's and the workspace's. */
+    /** `content/`, when it exists: this machine's clones. */
+    contentShips?: string;
+    /** `context.local.json`, when it exists: the directories of this machine the agent is bound to. */
+    bindingsShip?: string;
+    /** The agent's node_modules, when it exists. */
     depDirs: string[];
 }
-export declare function buildContextPaths(workspace: string, agentDir: string, agentPrefix: string, authPath: string): Promise<BuildContextPaths>;
+export declare function buildContextPaths(agentDir: string, authPath: string): Promise<BuildContextPaths>;
 /** Interrogate BOTH ignore files deploy emits, when the author kept them. */
 export declare function checkKeptIgnoreFiles(ctx: {
-    workspace: string;
     agentDir: string;
-    agentPrefix: string;
     force: boolean;
     paths: BuildContextPaths;
 }, report: DeployReport): Promise<void>;