@sweny-ai/core 0.1.192 → 0.1.194

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/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";
@@ -1139,6 +1140,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) {

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/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.192",
+  "version": "0.1.194",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"
   },
-  "description": "Skill library, DAG workflow orchestration, and E2E browser testing powered by Claude",
+  "description": "Workflows for coding agents. One set of rules, a receipt for every run.",
   "license": "MIT",
   "engines": {
     "node": ">=22"
@@ -51,7 +51,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/workflows/*.yml dist/workflows/ && cp src/cli/try-fixture.json dist/cli/ && node scripts/build-workflow-browser.mjs && node scripts/write-public-schema.mjs",
@@ -93,13 +94,16 @@
     "directory": "packages/core"
   },
   "keywords": [
+    "ai-agents",
+    "coding-agents",
+    "claude-code",
+    "codex",
+    "acp",
     "workflow",
     "dag",
-    "skills",
-    "claude",
-    "ai",
+    "github-action",
+    "sandbox",
     "automation",
-    "devops",
     "sweny"
   ]
 }