@paleo/alcode 0.1.0 → 0.3.0

package/dist/cli.d.ts

@@ -15,9 +15,11 @@ export interface AlcodeArgs {
     protocol?: string;
     message?: string;
     model?: string;
+    meta?: string;
     guide: boolean;
     openclawGuide: boolean;
     help: boolean;
+    version: boolean;
 }
 export declare function parseAlcodeArgs(argv: string[]): AlcodeArgs;
 export declare function validateArgs(args: AlcodeArgs): string | undefined;

package/dist/cli.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { relative } from "node:path";
 import { parseArgs } from "node:util";
 import { renderGuide } from "./guide.js";
@@ -18,6 +19,10 @@ export async function main(options) {
         stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }
+    if (parsed.version) {
+        stdout.write(`${readPackageVersion()}\n`);
+        return 0;
+    }
     if (parsed.help) {
         stdout.write(renderHelp());
         return 0;
@@ -33,6 +38,12 @@ export async function main(options) {
     }
     return runSession(parsed, { cwd, env, stdout, stderr });
 }
+function readPackageVersion() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (!pkg.version)
+        throw new Error("alcode: package.json is missing 'version'");
+    return pkg.version;
+}
 // alcode always runs `claude` in the foreground and blocks until it exits. When OpenClaw drives
 // alcode, it wraps this call in its own `exec` tool (which backgrounds after `yieldMs` and wakes
 // the agent on exit) — alcode owns no backgrounding or callback of its own. The per-run session
@@ -64,6 +75,7 @@ function buildFrontmatter(parsed, now) {
         model: parsed.model ?? null,
         sessionId: null,
         command: formatCommand(parsed),
+        meta: parsed.meta ?? null,
         startedAt: now.toISOString(),
         endedAt: null,
         exitReason: null,
@@ -96,6 +108,8 @@ function formatCommand(parsed) {
         parts.push("--model", parsed.model);
     if (parsed.message)
         parts.push("--message", JSON.stringify(parsed.message));
+    if (parsed.meta)
+        parts.push("--meta", JSON.stringify(parsed.meta));
     return parts.join(" ");
 }
 export function parseAlcodeArgs(argv) {
@@ -108,9 +122,11 @@ export function parseAlcodeArgs(argv) {
             protocol: { type: "string" },
             message: { type: "string" },
             model: { type: "string" },
+            meta: { type: "string" },
             guide: { type: "boolean", default: false },
             "openclaw-guide": { type: "boolean", default: false },
             help: { type: "boolean", default: false },
+            version: { type: "boolean", short: "v", default: false },
         },
         strict: true,
     });
@@ -121,9 +137,11 @@ export function parseAlcodeArgs(argv) {
         protocol: values.protocol,
         message: values.message,
         model: values.model,
+        meta: values.meta,
         guide: values.guide === true,
         openclawGuide: values["openclaw-guide"] === true,
         help: values.help === true,
+        version: values.version === true,
     };
 }
 export function validateArgs(args) {
@@ -169,6 +187,7 @@ Usage:
   alcode --guide
   alcode --openclaw-guide
   alcode --help
+  alcode -v, --version
 
 Modes:
   --new                 Start a new session.
@@ -179,6 +198,9 @@ Options:
   --ticket <id>     Ticket ID. Required with --new + --protocol.
   --message "..."   Message to send. Required for spec, aad, and when no --protocol.
   --model <model>   Model override.
+  --meta "..."      Opaque handoff string, stored verbatim in the session file frontmatter
+                    (\`meta:\`). alcode never interprets it; a later reader of the session file
+                    (e.g. the caller reporting the run's outcome) can use it.
 
 Env:
   ALIGNFIRST_CODE_SKIP_PERMISSIONS 1 to run the coding agent with permission prompts disabled.

package/dist/session-file.d.ts

@@ -5,6 +5,7 @@ export interface SessionFrontmatter {
     model: string | null;
     sessionId: string | null;
     command: string;
+    meta: string | null;
     startedAt: string;
     endedAt: string | null;
     exitReason: string | null;

package/dist/session-file.js

@@ -94,6 +94,7 @@ export function parseFrontmatter(block) {
         model: map.model ?? null,
         sessionId: map.sessionId ?? null,
         command: map.command ?? "",
+        meta: map.meta ?? null,
         startedAt: map.startedAt ?? "",
         endedAt: map.endedAt ?? null,
         exitReason: map.exitReason ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/alcode",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "Run a coding agent through AlignFirst protocols, with a durable session file per run.",

package/templates/guide-run-openclaw.md

@@ -2,3 +2,4 @@ Under OpenClaw, background it through the `exec` tool:
 
 - Pass `background: true` and `timeout: 0` (no kill timer). Never rely on the auto-yield or a finite timeout.
 - Set the exec `workdir` to the project root as an **absolute** path (`~` is not expanded there), or `cd` into the project inside the command itself.
+- If the outcome must be reported into a thread **you created yourself** via `message` `action: "thread-create"`, add `--meta "<THREAD_ID>"` with that thread's `chat_id`: the completion wake's plain reply goes to this session's default surface (the channel), and only the session file's `meta` can point your report back at the thread (via `message` `action: "thread-reply"`). In every other case omit `--meta` — platform-threaded replies and thread-bound sessions already report in the right place.

package/templates/guide.md

@@ -22,8 +22,8 @@ Every run writes a session file under `.plans/`: `.plans/<ticket>/coding-session
 
 {{WAKE}}
 
-1. **Read the run's session file** (the path `alcode` printed on its first line, under `coding-sessions/`). Its frontmatter holds `status` (`succeeded` / `failed`) and the session id; the `---- Result ----` block holds the outcome.
-2. **Report the outcome to the user** where the work was requested. Send one concise message: succeeded or failed, plus a one-line summary of the result for the audience.
+1. **Read the run's session file** (the path `alcode` printed on its first line, under `coding-sessions/`). Its frontmatter holds `status` (`succeeded` / `failed`) and the session id; the `---- Result ----` block holds the outcome. If you set `meta` at launch, it is there too.
+2. **Report the outcome to the user** where the work was requested. Send one concise message: succeeded or failed, plus a one-line summary of the result for the audience. If the frontmatter `meta` carries a destination (e.g. a thread target), route this report there — a plain reply from the wake turn goes to the session's default surface, which may not be where the work was requested.
 3. Do **not** re-verify the repo, re-run the coding agent, fetch/merge branches, or inspect `git`. The coding agent already did the work and the session file is authoritative. Relay its outcome, nothing more.
 
 If the session file says the run failed, report that plainly and propose the next step; don't silently retry.
@@ -44,6 +44,7 @@ alcode --resume <sessionId> [--protocol <protocol>] [--message "..."]
 | `--ticket <id>` | Ticket ID. Required with `--new` + `--protocol`. |
 | `--message "..."` | Message to send. Required for `spec`, `aad`, and when no `--protocol`. |
 | `--model <model>` | Model override. |
+| `--meta "..."` | Opaque handoff string stored verbatim in the session file's `meta:` frontmatter. `alcode` never reads it — it's for you to stash context the run's later reader needs (e.g. where to report the outcome). |
 
 For `--new` runs, the `Session ID:` is printed to stdout and written to the session file frontmatter (the durable source of truth). Save it to resume the conversation later.