@sweny-ai/core 0.1.193 → 0.1.195

package/README.md

@@ -0,0 +1,57 @@
+# @sweny-ai/core
+
+**Workflows for coding agents. One set of rules, a receipt for every run.**
+
+SWEny runs a DAG of coding-agent steps from a YAML file, on your laptop or in CI. The agent does the work. SWEny decides what it can touch, checks what it hands back, and records what it did.
+
+## Start
+
+```bash
+npx @sweny-ai/core new                  # pick a named workflow, e.g. explain-repo (no skill credentials)
+npx @sweny-ai/core check                # preflight: is your agent logged in?
+npx @sweny-ai/core workflow run .sweny/workflows/explain-repo.yml
+```
+
+Install once with `npm install -g @sweny-ai/core` and the binary is `sweny`. Want to watch it first? `sweny try` replays a recorded demo with no login and no network (sample data, not a real run).
+
+## Credentials
+
+Requires Node 20+ and a login or API key for the agent that runs your nodes. Claude Code is the default; pick another with `--agent`.
+
+| Agent | Credentials it needs |
+|-------|----------------------|
+| Claude Code (default) | `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`), or `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`, or a Claude Code login (`claude`, then `/login`), or Bedrock / Vertex routing. |
+| Codex (`--agent codex`) | `CODEX_API_KEY`, `OPENAI_API_KEY` or `CODEX_ACCESS_TOKEN`, or a `codex login`. |
+| pi (`--agent pi`) | The API key of the model provider pi calls (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, ...). |
+| ACP agent (`--agent "acp:<command>"`) | Whatever that agent needs; pass its key var through `SWENY_ENV_PASSTHROUGH`. |
+
+For Claude Code and Codex, `sweny check` and `sweny workflow run` stop with the fix when no credential or login is found, before any node runs. Skill credentials (`GITHUB_TOKEN` and so on) are separate and only needed by workflows that use those skills.
+
+## What you get
+
+Every run ends with a receipt: nodes, tool calls, duration, tokens, cost, and the policy the agent ran under. An example:
+
+```text
+╭┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄╮
+┆ ✓ passed                          run 3f9a2c ┆
+┆ explain-repo                                 ┆
+┆                                              ┆
+┆ nodes       2/2                              ┆
+┆ tool calls  12                               ┆
+┆ duration    28s                              ┆
+┆ tokens      30k                              ┆
+┆ cost        $0.13                            ┆
+┆ policy      env scoped, sandbox on           ┆
+├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
+┆          [ ENV SCOPED · SANDBOXED ]          ┆
+╰┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄╯
+```
+
+Then `sweny runs` lists your history, and `sweny runs diff` shows what changed in the answers between two runs. The [GitHub Action](https://docs.sweny.ai/action/) posts the same receipt on a PR, and recurring [packs](https://docs.sweny.ai/workflows/packs/) (weekly digest, dependency drift, PR risk review) run it on a schedule.
+
+## Links
+
+- [Quick start](https://docs.sweny.ai/getting-started/quick-start/)
+- [CLI reference](https://docs.sweny.ai/cli/commands/)
+- [Agents and policies](https://docs.sweny.ai/getting-started/agents-and-policies/)
+- [Source and issues](https://github.com/swenyai/sweny)

package/dist/browser.d.ts

@@ -13,7 +13,7 @@
  *   - `buildWorkflow` / `refineWorkflow` — depend on the Claude interface.
  *   - Testing helpers — `MockClaude`, `createFileSkill` use `node:fs`.
  */
-export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, EdgeWhen, WhenExpression, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, } from "./types.js";
+export type { Skill, SkillCategory, Tool, ToolContext, ToolRunContext, ConfigField, JSONSchema, Workflow, Node, Edge, EdgeWhen, WhenExpression, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, } from "./types.js";
 export { consoleLogger } from "./types.js";
 export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, } from "./types.js";
 export { github, linear, slack, sentry, datadog, betterstack, notification, supabase, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";

package/dist/cli/comment-output.d.ts

@@ -1,7 +1,9 @@
 /**
- * PR billboard: the markdown a CI runner posts as one sticky comment on a
- * pull request. Leads with the receipt ticket, then the run's DAG. Pure and runner-agnostic; the CLI writes it with
- * `--comment-file`, and any runner (the GitHub Action, GitLab, a script) posts it.
+ * PR billboard. Quiet by default (#536): `--comment-file` now writes an empty
+ * file, so the Action's poster (scripts/post-run-comment.sh skips an empty
+ * file) adds nothing to the PR. The receipt and DAG go to the job summary, and
+ * findings go in the workflow's one updating comment (pr-comment.ts). The
+ * formatters below remain for the offline demo (`sweny try`).
  *
  * METADATA ONLY. Node names, statuses, counts, and durations. Never prompts,
  * tool inputs, node outputs, errors, or model prose. The optional "since last
@@ -9,6 +11,7 @@
  */
 import type { ExecutionTrace, NodeResult, Workflow } from "../types.js";
 import { type RunSummary } from "./run-output.js";
+import { prCommentMarker } from "../pr-comment.js";
 export declare const RUN_COMMENT_FOOTER = "Run with [SWEny](https://github.com/swenyai/sweny): `npx @sweny-ai/core new`";
 export interface RunCommentOptions {
     trace?: ExecutionTrace;
@@ -19,8 +22,8 @@ export interface RunCommentOptions {
     /** Pre-rendered "since last run" markdown line (run-answers.ts formatSinceLastMarkdown): counts only. */
     sinceLast?: string | null;
 }
-/** Hidden marker the poster searches for to update the comment in place. */
-export declare function runCommentMarker(workflowId: string): string;
+/** Hidden marker the poster searches for to update the comment in place (the findings comment's marker too). */
+export declare const runCommentMarker: typeof prCommentMarker;
 export declare function formatRunComment(workflow: Workflow, results: Map<string, NodeResult>, summary: RunSummary, opts?: RunCommentOptions): string;
 /**
  * Minimal comment for a run that crashed before producing node results: no DAG
@@ -28,7 +31,8 @@ export declare function formatRunComment(workflow: Workflow, results: Map<string
  * success comment for the same workflow.
  */
 export declare function formatCrashComment(workflow: Workflow, summary: RunSummary, runId?: string): string;
-/** Write the comment markdown to `file`. Never throws; returns true only when written. */
-export declare function writeRunComment(file: string, workflow: Workflow, results: Map<string, NodeResult>, summary: RunSummary, opts?: RunCommentOptions & {
-    crashed?: boolean;
-}): boolean;
+/**
+ * Write an empty comment file: no metadata-only comment on the PR. Truncates a
+ * file an earlier step left there. Never throws; returns true only when written.
+ */
+export declare function writeRunComment(file: string): boolean;

package/dist/cli/comment-output.js

@@ -1,27 +1,27 @@
 /**
- * PR billboard: the markdown a CI runner posts as one sticky comment on a
- * pull request. Leads with the receipt ticket, then the run's DAG. Pure and runner-agnostic; the CLI writes it with
- * `--comment-file`, and any runner (the GitHub Action, GitLab, a script) posts it.
+ * PR billboard. Quiet by default (#536): `--comment-file` now writes an empty
+ * file, so the Action's poster (scripts/post-run-comment.sh skips an empty
+ * file) adds nothing to the PR. The receipt and DAG go to the job summary, and
+ * findings go in the workflow's one updating comment (pr-comment.ts). The
+ * formatters below remain for the offline demo (`sweny try`).
  *
  * METADATA ONLY. Node names, statuses, counts, and durations. Never prompts,
  * tool inputs, node outputs, errors, or model prose. The optional "since last
  * run" line carries counts of added and resolved answers, never their text.
  */
-import { workspaceRoot, writeFileNoFollow } from "../safe-file.js";
 import { toMermaidBlock } from "../mermaid.js";
 import { formatReceiptDuration, nodeStates } from "./run-output.js";
 import { formatTicketText } from "./ticket.js";
 import { glyphs } from "./terminal.js";
+import { workspaceRoot, writeFileNoFollow } from "../safe-file.js";
+import { prCommentMarker } from "../pr-comment.js";
 export const RUN_COMMENT_FOOTER = "Run with [SWEny](https://github.com/swenyai/sweny): `npx @sweny-ai/core new`";
 /** The receipt ticket as a fenced block, the same card a TTY run ends on. */
 function ticketBlock(workflow, summary, runId, crashed) {
     return ["```text", formatTicketText({ summary, workflow: workflow.id, runId, crashed }), "```"].join("\n");
 }
-/** Hidden marker the poster searches for to update the comment in place. */
-export function runCommentMarker(workflowId) {
-    const safe = workflowId.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/-{2,}/g, "-") || "workflow";
-    return `<!-- sweny-run-comment:${safe} -->`;
-}
+/** Hidden marker the poster searches for to update the comment in place (the findings comment's marker too). */
+export const runCommentMarker = prCommentMarker;
 /** Table-cell-safe text: no pipes, newlines, or backticks. */
 function cell(text) {
     return text.replace(/\s+/g, " ").replace(/\|/g, "\\|").replace(/`/g, "'").trim();
@@ -75,13 +75,14 @@ export function formatCrashComment(workflow, summary, runId) {
         "",
     ].join("\n");
 }
-/** Write the comment markdown to `file`. Never throws; returns true only when written. */
-export function writeRunComment(file, workflow, results, summary, opts = {}) {
+/**
+ * Write an empty comment file: no metadata-only comment on the PR. Truncates a
+ * file an earlier step left there. Never throws; returns true only when written.
+ */
+export function writeRunComment(file) {
     try {
         // The file may sit in the agent-writable workspace: no link on the path is followed.
-        writeFileNoFollow(file, opts.crashed
-            ? formatCrashComment(workflow, summary, opts.runId)
-            : formatRunComment(workflow, results, summary, opts), { ...workspaceRoot(file), mode: 0o644, dirMode: 0o755 });
+        writeFileNoFollow(file, "", { ...workspaceRoot(file), mode: 0o644, dirMode: 0o755 });
         return true;
     }
     catch (err) {

package/dist/cli/first-success.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The "what next" note after a workspace's first successful real run (#534).
+ *
+ * `sweny try` ends with one command to run next; a real run used to end in
+ * silence, at the exact moment a user has just seen value. This prints one
+ * short block (history, compare, schedule) once per workspace.
+ *
+ * Once means once per workspace for this user: the marker lives in sweny's
+ * per-user state dir (`<state>/first-success/<workspace hash>`), never in the
+ * repo, so it is not committed and an agent in the workspace cannot reset it.
+ * The marker is claimed atomically (`wx`), so two runs finishing together
+ * print the note once.
+ *
+ * Silent when: CI, a failed run, `--json`, `--stream`, `--dry-run`, or the
+ * marker already exists. A marker that cannot be written means no note: a
+ * note that might repeat is worse than none. Every other output (a TTY, a
+ * pipe, NO_COLOR) gets the same words; only the paint and glyphs change, and
+ * the last line is always plain text.
+ */
+import { type Paint } from "./style.js";
+type Env = Record<string, string | undefined>;
+/** How to schedule a workflow you wrote: the Action's cron and dispatch triggers. */
+export declare const SCHEDULING_DOCS_URL = "https://docs.sweny.ai/action/scheduling/";
+/** The two command steps, in order. Commands are real subcommands (a spec asserts it). */
+export declare const WHAT_NEXT_STEPS: ReadonlyArray<{
+    command: string;
+    what: string;
+}>;
+/** The third step, and the plain closing line. */
+export declare const WHAT_NEXT_SCHEDULE = "Run it on a schedule: https://docs.sweny.ai/action/scheduling/";
+/** CI: the `CI` convention, or GitHub Actions itself. */
+export declare function inCi(env?: Env): boolean;
+/**
+ * The note: a heading, one aligned row per step, then a plain closing line
+ * that says how to schedule it. Same words with or without color or Unicode.
+ */
+export declare function formatWhatNext(paint?: Paint, unicode?: boolean): string;
+/** `<state>/first-success/<workspace hash>`: one empty file per workspace. */
+export declare function firstSuccessMarker(cwd: string, env?: Env): string;
+/**
+ * Claim the workspace's marker. True only for the caller that created it.
+ * False when it already exists or cannot be written (read-only home, no
+ * state dir): the note then stays silent rather than risk repeating.
+ */
+export declare function claimFirstSuccess(cwd: string, env?: Env): boolean;
+export interface WhatNextOptions {
+    /** Where the note goes: the run's stdout. */
+    stream: {
+        write(s: string): unknown;
+        isTTY?: boolean;
+    };
+    /** The run succeeded (no failed node, not crashed). Anything else prints nothing. */
+    ok: boolean;
+    /** `--json`, `--stream` or `--dry-run`: stdout is data, or nothing real ran. */
+    quiet?: boolean;
+    env?: Env;
+    cwd?: string;
+    /** Override color. Default: `colorEnabled(stream, env)`. */
+    color?: boolean;
+    /** Override Unicode. Default: `supportsUnicode(env)`. */
+    unicode?: boolean;
+}
+/** Print the note if this is the workspace's first successful real run. Returns whether it printed. */
+export declare function writeWhatNext(opts: WhatNextOptions): boolean;
+export {};

package/dist/cli/first-success.js

@@ -0,0 +1,81 @@
+/**
+ * The "what next" note after a workspace's first successful real run (#534).
+ *
+ * `sweny try` ends with one command to run next; a real run used to end in
+ * silence, at the exact moment a user has just seen value. This prints one
+ * short block (history, compare, schedule) once per workspace.
+ *
+ * Once means once per workspace for this user: the marker lives in sweny's
+ * per-user state dir (`<state>/first-success/<workspace hash>`), never in the
+ * repo, so it is not committed and an agent in the workspace cannot reset it.
+ * The marker is claimed atomically (`wx`), so two runs finishing together
+ * print the note once.
+ *
+ * Silent when: CI, a failed run, `--json`, `--stream`, `--dry-run`, or the
+ * marker already exists. A marker that cannot be written means no note: a
+ * note that might repeat is worse than none. Every other output (a TTY, a
+ * pipe, NO_COLOR) gets the same words; only the paint and glyphs change, and
+ * the last line is always plain text.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { swenyStateDir, workspaceScope } from "../journal.js";
+import { createPaint } from "./style.js";
+import { colorEnabled, glyphsFor, supportsUnicode } from "./terminal.js";
+/** How to schedule a workflow you wrote: the Action's cron and dispatch triggers. */
+export const SCHEDULING_DOCS_URL = "https://docs.sweny.ai/action/scheduling/";
+/** The two command steps, in order. Commands are real subcommands (a spec asserts it). */
+export const WHAT_NEXT_STEPS = [
+    { command: "sweny runs", what: "see this run and the ones before it" },
+    { command: "sweny runs diff", what: "run it again, then see what changed in the answers" },
+];
+/** The third step, and the plain closing line. */
+export const WHAT_NEXT_SCHEDULE = `Run it on a schedule: ${SCHEDULING_DOCS_URL}`;
+function truthy(v) {
+    return v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false";
+}
+/** CI: the `CI` convention, or GitHub Actions itself. */
+export function inCi(env = process.env) {
+    return truthy(env.CI) || env.GITHUB_ACTIONS === "true";
+}
+/**
+ * The note: a heading, one aligned row per step, then a plain closing line
+ * that says how to schedule it. Same words with or without color or Unicode.
+ */
+export function formatWhatNext(paint = createPaint(false), unicode = true) {
+    const g = glyphsFor(unicode);
+    const width = Math.max(...WHAT_NEXT_STEPS.map((s) => s.command.length));
+    const rows = WHAT_NEXT_STEPS.map((s) => `    ${paint.strong(s.command.padEnd(width))}  ${paint.muted(s.what)}`);
+    return [`  ${paint.brand(g.brand)} ${paint.strong("Next")}`, ...rows, `  ${WHAT_NEXT_SCHEDULE}`].join("\n");
+}
+/** `<state>/first-success/<workspace hash>`: one empty file per workspace. */
+export function firstSuccessMarker(cwd, env = process.env) {
+    return path.join(swenyStateDir(env), "first-success", workspaceScope(cwd));
+}
+/**
+ * Claim the workspace's marker. True only for the caller that created it.
+ * False when it already exists or cannot be written (read-only home, no
+ * state dir): the note then stays silent rather than risk repeating.
+ */
+export function claimFirstSuccess(cwd, env = process.env) {
+    const file = firstSuccessMarker(cwd, env);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        fs.closeSync(fs.openSync(file, "wx", 0o600));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Print the note if this is the workspace's first successful real run. Returns whether it printed. */
+export function writeWhatNext(opts) {
+    const env = opts.env ?? process.env;
+    if (!opts.ok || opts.quiet || inCi(env))
+        return false;
+    if (!claimFirstSuccess(opts.cwd ?? process.cwd(), env))
+        return false;
+    const paint = createPaint(opts.color ?? colorEnabled(opts.stream, env));
+    opts.stream.write(`${formatWhatNext(paint, opts.unicode ?? supportsUnicode(env))}\n\n`);
+    return true;
+}

package/dist/cli/main.js

@@ -45,6 +45,7 @@ import { createStreamObserver } from "./stream-observer.js";
 import { createRunLogger, summarizeRun, writeStepSummary, WORKFLOW_RUN_DESCRIPTION, WORKFLOW_RUN_OPTIONS, } from "./run-output.js";
 import { writeRunComment } from "./comment-output.js";
 import { writeReceipt } from "./ticket.js";
+import { writeWhatNext } from "./first-success.js";
 import { createNodeProgress, toolCallsText } from "./progress.js";
 import { applyNoColor, createPaint } from "./style.js";
 import { colorEnabled, glyphsFor, richOutput, spinnerFramesFor, supportsUnicode } from "./terminal.js";
@@ -1029,6 +1030,8 @@ resume) {
     // --max-steps overrides the executor's own DEFAULT_MAX_STEPS when set.
     const wfTimeoutMs = budget.timeoutMs;
     const wfMaxSteps = budget.maxSteps;
+    // The job summary is written once: by the finished run, else by the crash path.
+    let stepSummaryWritten = false;
     try {
         const { results, trace } = await runWithWallClockBudget((signal) => execute(workflow, workflowInput, {
             skills,
@@ -1073,16 +1076,12 @@ resume) {
         catch {
             // silent
         }
-        // PR billboard markdown (metadata only). Written before any early exit so
-        // --json runs and failed runs still get a comment.
-        if (options.commentFile) {
-            writeRunComment(options.commentFile, workflow, results, summarizeRun(results, wfDurationMs, false, trace), {
-                trace,
-                durationsMs: Object.fromEntries(nodeTimer.durations),
-                runId,
-                sinceLast: sinceLast ? formatSinceLastMarkdown(sinceLast) : null,
-            });
-        }
+        // Receipt metadata belongs in the job summary, including --json and failed runs.
+        stepSummaryWritten = true;
+        writeStepSummary(workflow, results, summarizeRun(results, wfDurationMs, false, trace), trace, process.env, sinceLast ? formatSinceLastMarkdown(sinceLast) : null);
+        // Quiet by default (#536): an empty comment file, so no metadata-only PR comment.
+        if (options.commentFile)
+            writeRunComment(options.commentFile);
         if (isJson) {
             await writeResultJson(results, outputSecrets(skills));
             process.exit(wfHasFailed ? 1 : 0);
@@ -1103,10 +1102,9 @@ resume) {
         catch {
             // silent
         }
-        // Run receipt (metadata only) + optional $GITHUB_STEP_SUMMARY.
+        // Run receipt (metadata only). The job summary was written before early exits.
         runLogger.flush();
         const receipt = summarizeRun(results, wfDurationMs, false, trace);
-        writeStepSummary(workflow, results, receipt, trace, process.env, sinceLast ? formatSinceLastMarkdown(sinceLast) : null);
         // The answer, above the receipt: the terminal node's result, or the failed node's error.
         // Also saved to .sweny/runs/<id>/output.md (local only; --no-history skips the file).
         // Redacted with the journal's redactor; in CI printed only with --show-output.
@@ -1139,6 +1137,12 @@ resume) {
         await writeReceipt(receipt, { workflow: workflow.id, runId, stream: process.stdout });
         if (sinceLast)
             console.log(createPaint(colorEnabled(process.stdout)).muted(`  ${formatSinceLast(sinceLast)}`));
+        // First successful real run in this workspace: one "what next" note (#534).
+        writeWhatNext({
+            stream: process.stdout,
+            ok: true,
+            quiet: Boolean(options.stream) || config.dryRun,
+        });
         process.exit(0);
     }
     catch (err) {
@@ -1158,10 +1162,11 @@ resume) {
         recordHistory(nodeTimer.lastResults, undefined, true);
         const crashSummary = summarizeRun(new Map(), Date.now() - runStart, true);
         await writeReceipt(crashSummary, { workflow: workflow.id, runId, crashed: true, stream: process.stderr });
-        // A crash must not leave a stale success comment behind.
-        if (options.commentFile) {
-            writeRunComment(options.commentFile, workflow, new Map(), crashSummary, { crashed: true, runId });
-        }
+        // A crash records its receipt in the job summary; the PR gets no status comment.
+        if (!stepSummaryWritten)
+            writeStepSummary(workflow, new Map(), crashSummary);
+        if (options.commentFile)
+            writeRunComment(options.commentFile);
         // Finalize the cloud run as failed (covers thrown errors, incl.
         // RouteEvaluationError). Without this a crashed workflow run stays
         // "running" in cloud forever.

package/dist/cli/new.d.ts

@@ -9,6 +9,7 @@
  */
 import { type WorkflowTemplate } from "./templates.js";
 import { type Skill } from "../types.js";
+import { SCHEDULING_DOCS_URL } from "./first-success.js";
 export interface Credential {
     key: string;
     hint?: string;
@@ -171,3 +172,11 @@ export declare function runNew(options?: {
     /** Internal: the id came from the marketplace picker, skip the built-in shortcut. */
     forceMarketplace?: boolean;
 }): Promise<void>;
+export { SCHEDULING_DOCS_URL };
+/**
+ * The closing line (#534). A pack already shows its own trigger step, so it
+ * closes as before. Any other workflow that was written (a starter or a
+ * described one) says how to schedule THIS workflow; it never names another
+ * pack, because no template metadata says which pack would suit it.
+ */
+export declare function outroMessage(hasExistingConfig: boolean, offerSchedule: boolean): string;

package/dist/cli/new.js

@@ -20,6 +20,7 @@ import { configuredSkills } from "../skills/custom-loader.js";
 import { builtinSkills } from "../skills/index.js";
 import { DagRenderer } from "./renderer.js";
 import { runE2eInit } from "./e2e.js";
+import { SCHEDULING_DOCS_URL } from "./first-success.js";
 // ── Skill → Credential extras ─────────────────────────────────────────
 /**
  * Supplementary metadata (URLs, hints, defaults) for env vars.
@@ -853,7 +854,18 @@ export async function runNew(options) {
         steps.push(`${stepNum++}. Create your first workflow:`, `   ${cli} new`);
     }
     p.note(steps.join("\n"), "Next steps");
-    p.outro(hasExistingConfig ? "Workflow added!" : "You're all set!");
+    p.outro(outroMessage(hasExistingConfig, Boolean(template) && !template?.pack));
+}
+export { SCHEDULING_DOCS_URL };
+/**
+ * The closing line (#534). A pack already shows its own trigger step, so it
+ * closes as before. Any other workflow that was written (a starter or a
+ * described one) says how to schedule THIS workflow; it never names another
+ * pack, because no template metadata says which pack would suit it.
+ */
+export function outroMessage(hasExistingConfig, offerSchedule) {
+    const done = hasExistingConfig ? "Workflow added!" : "You're all set!";
+    return offerSchedule ? `${done} Run it on a schedule: ${SCHEDULING_DOCS_URL}` : done;
 }
 // ── Custom workflow branch ────────────────────────────────────────────
 /**

package/dist/cli/packs.js

@@ -1000,8 +1000,7 @@ nodes:
       (type comment). It can only land on context.input.pr_number; sweny
       posts it after this step.
 
-      Start the body with the line: <!-- sweny-pr-risk -->
-      Then: "Risk: LEVEL" with the size, then the reasons as short bullets
+      Start the body with "Risk: LEVEL" and the size, then the reasons as short bullets
       (each naming its evidence), then the focus pointers, then a last line:
       "Read-only scope review. No code was changed."
       Keep it under 15 lines. No emoji walls, no praise.
@@ -1053,7 +1052,7 @@ on:
 
 permissions:
   contents: read
-  pull-requests: write # the review comment and the run billboard
+  pull-requests: write # the one review comment, updated in place
 
 concurrency:
   group: sweny-pr-risk-\${{ github.event.pull_request.number }}

package/dist/cli/record.d.ts

@@ -55,7 +55,7 @@ export declare function buildTimeline(lines: string[], fixture: TryFixture): {
 /** Render the timeline as a self-contained animated SVG. Pure and deterministic. */
 export declare function renderRecordingSvg(lines: string[], fixture: TryFixture): string;
 /**
- * The PR-comment preview (heading plus DAG) sits between the answer and the
+ * The job summary preview (heading plus DAG) sits between the answer and the
  * ticket. The recording drops it to stay a README-sized hero: tagline, nodes,
  * answer, ticket.
  */

package/dist/cli/record.js

@@ -17,7 +17,7 @@ import fs from "node:fs";
 import path from "node:path";
 import chalk from "chalk";
 import { GLYPHS, PALETTE, ROLE_COLORS, SPINNER_FRAMES, SURFACE_COLORS } from "../theme.js";
-import { loadTryFixture, runTry } from "./try.js";
+import { loadTryFixture, runTry, SUMMARY_PREVIEW_LEAD } from "./try.js";
 /** Terminal width the demo is rendered at (the ticket and DAG are designed for 80). */
 export const RECORD_COLUMNS = 80;
 /** Lines longer than this wrap in the window, like a terminal would. */
@@ -292,12 +292,12 @@ export function renderRecordingSvg(lines, fixture) {
 // ── Entry points ────────────────────────────────────────────────
 const stripAnsi = (s) => s.replace(/\x1B\[[0-9;]*[A-Za-z]/g, "");
 /**
- * The PR-comment preview (heading plus DAG) sits between the answer and the
+ * The job summary preview (heading plus DAG) sits between the answer and the
  * ticket. The recording drops it to stay a README-sized hero: tagline, nodes,
  * answer, ticket.
  */
 export function dropCommentPreview(lines) {
-    const from = lines.findIndex((l) => stripAnsi(l).includes("On a pull request, CI posts"));
+    const from = lines.findIndex((l) => stripAnsi(l).includes(SUMMARY_PREVIEW_LEAD));
     const to = lines.findIndex((l, i) => i > from && stripAnsi(l).startsWith("  \u256D"));
     if (from < 0 || to < 0)
         return lines;

package/dist/cli/run-output.js

@@ -320,7 +320,7 @@ export const WORKFLOW_RUN_OPTIONS = [
     ["--mermaid", "Output a Mermaid diagram with execution state after run"],
     [
         "--comment-file <path>",
-        "Write a PR-comment markdown (run receipt, status-colored DAG, per-node table; metadata only) to <path> so any CI can post it",
+        "Write an empty PR-comment file at <path> (kept for the Action; the receipt and DAG go to the job summary)",
     ],
     ["--input <json>", "JSON string of input data to pass to the workflow"],
     ["--agent <id>", "Coding agent that runs the nodes: claude (default), codex, or pi (experimental)"],

package/dist/cli/try.d.ts

@@ -95,6 +95,8 @@ export interface TryOptions {
     fixture?: TryFixture;
 }
 export declare const DEFAULT_TRY_PACE_MS = 1200;
+/** The line that opens the job summary preview (record.ts cuts the preview from here). */
+export declare const SUMMARY_PREVIEW_LEAD = "In CI, the job summary gets this heading, this DAG and the receipt below:";
 /** Replay the recording. Returns the process exit code. */
 export declare function runTry(opts?: TryOptions): Promise<number>;
 export declare function registerTryCommand(program: Command): Command;

package/dist/cli/try.js

@@ -176,6 +176,8 @@ export function formatTryNext(paint = createPaint(false)) {
 }
 export const DEFAULT_TRY_PACE_MS = 1200;
 const silentLogger = { info() { }, warn() { }, error() { }, debug() { } };
+/** The line that opens the job summary preview (record.ts cuts the preview from here). */
+export const SUMMARY_PREVIEW_LEAD = "In CI, the job summary gets this heading, this DAG and the receipt below:";
 /** Replay the recording. Returns the process exit code. */
 export async function runTry(opts = {}) {
     const write = opts.write ?? ((s) => void process.stdout.write(s));
@@ -247,9 +249,9 @@ export async function runTry(opts = {}) {
     const answer = resolveFinalOutput(workflow, results);
     if (answer)
         write(`${formatFinalOutput(answer)}\n\n`);
-    // Compact preview of the PR comment: its heading and DAG here, its ticket (the receipt) below.
+    // Compact preview of CI's job summary: heading and DAG here, receipt below.
     const comment = formatRunComment(workflow, results, receipt, { trace, durationsMs });
-    write(`  ${paint.muted("On a pull request, CI posts this heading, this DAG and the receipt below:")}\n\n`);
+    write(`  ${paint.muted(SUMMARY_PREVIEW_LEAD)}\n\n`);
     const tone = receipt.ok ? paint.success : paint.error;
     write(`    ${tone(receipt.ok ? g.success : g.failure)} ${paint.strong(workflow.name)}\n\n`);
     write(`${dag

package/dist/executor.js

@@ -26,6 +26,7 @@ import { gitCredentialWarning, scanGitCredentials } from "./git-credentials.js";
 // #473: the sweny-side branch push in `github_create_pr` (Node only; skills/ stays browser-safe).
 import { bindBranchPusher } from "./skills/git-push.js";
 import { trustedEnvValue } from "./startup-env.js";
+import { toolRunContext } from "./run-context.js";
 import { fenceUntrusted, fenceUntrustedJson } from "./untrusted.js";
 import { asClaude } from "./harness/compat.js";
 import { budgetGate, isToolClass, policyGate, resolveHarnessPolicy } from "./harness/policy.js";
@@ -213,6 +214,8 @@ async function executeRun(workflow, input, options, results, trace, at) {
     const pushBranch = bindBranchPusher(resolveCwd, runEnv);
     // GHES: the REST base for the github skill, never a value the workspace .env introduced.
     const githubApiUrl = trustedEnvValue(runEnv, "GITHUB_API_URL") || undefined;
+    // The run's identity and job-summary writer, the same for every tool, from the operator's env.
+    const runToolContext = toolRunContext(workflow.id, runEnv);
     const resolvedSources = await resolveSources(sourceMap, {
         cwd: resolveCwd,
         env: options.env ?? process.env,
@@ -421,6 +424,7 @@ async function executeRun(workflow, input, options, results, trace, at) {
                     staged: stageOutputs,
                     pushBranch,
                     ...(githubApiUrl ? { githubApiUrl } : {}),
+                    ...runToolContext,
                 };
                 const output = await t.handler(toolInput, toolCtx);
                 safeObserve(observer, { type: "tool:result", node: currentId, tool: t.name, output }, logger);
@@ -832,6 +836,7 @@ async function executeRun(workflow, input, options, results, trace, at) {
                     cwd: resolveCwd,
                     pushBranch,
                     ...(githubApiUrl ? { githubApiUrl } : {}),
+                    ...runToolContext,
                     state: writeState,
                     logger,
                     input: runInput,

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  * })
  * ```
  */
-export type { Skill, SkillCategory, SkillDefinition, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, EdgeWhen, WhenExpression, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, Source, ResolvedSource, SourceKind, SourceResolutionMap, WorkflowInputs, WorkflowInputField, WorkflowInputType, InputValidationError, InputValidationResult, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, NodeAccess, NodePermissions, NodePermissionsSpec, SafeOutputType, SafeOutputDeclaration, SafeOutputsPolicy, SafeOutputReceipt, SafeOutputPin, AuthorAssociation, } from "./types.js";
+export type { Skill, SkillCategory, SkillDefinition, Tool, ToolContext, ToolRunContext, ConfigField, JSONSchema, Workflow, Node, Edge, EdgeWhen, WhenExpression, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, TraceStep, TraceEdge, ExecutionTrace, ExecutionResult, Source, ResolvedSource, SourceKind, SourceResolutionMap, WorkflowInputs, WorkflowInputField, WorkflowInputType, InputValidationError, InputValidationResult, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, NodeAccess, NodePermissions, NodePermissionsSpec, SafeOutputType, SafeOutputDeclaration, SafeOutputsPolicy, SafeOutputReceipt, SafeOutputPin, AuthorAssociation, } from "./types.js";
 export { WORKFLOW_INPUT_TYPES } from "./types.js";
 export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, NODE_ACCESS, TOOL_CLASSES, SAFE_OUTPUT_TYPES, SAFE_OUTPUT_APPLIERS, AUTHOR_ASSOCIATIONS, } from "./types.js";
 export { consoleLogger } from "./types.js";

package/dist/journal.js

@@ -1411,7 +1411,7 @@ async function probeProvider(toolName, args, key, skill, ctx, since) {
         return { state: "unknown", reason: err instanceof Error ? err.message : String(err) };
     }
 }
-/** The ids a write produced, nothing else (refs and URLs for receipts). */
+/** The ids a write produced and a skip reason, nothing else (refs, URLs and skips for receipts). */
 function slimOutput(o, depth = 0) {
     if (!o || typeof o !== "object" || Array.isArray(o) || depth > 3)
         return null;
@@ -1425,7 +1425,7 @@ function slimOutput(o, depth = 0) {
             out.transient = true;
     }
     for (const [k, v] of Object.entries(o)) {
-        if (["number", "identifier", "id", "html_url", "url", "success", "reused"].includes(k)) {
+        if (["number", "identifier", "id", "html_url", "url", "success", "reused", "skipped"].includes(k)) {
             if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
                 out[k] = v;
         }