@gapi/gcli 1.8.244 → 1.8.246

package/.agents/skills/local-ai-runners/SKILL.md

@@ -29,6 +29,11 @@ security, symptom table): `graphql-server/docs/features/local-ai-runners.md`.
   for "token refused" in sync with `RestartPreventExitStatus`. Tests must
   pass an explicit home dir to `SystemdUserService` (os.homedir() ignored a
   changed HOME under jest and wrote into the real `~/.config` once).
+  `runner:daemon:start`/`:restart` check the outcome after ~2 s
+  (`reportStarted`, exit 78 -> the `--reset` hint) - a refused runner exits
+  within a second, so "started" alone would be a lie. Your local `gcli` and
+  the installed unit may both run this repo's `release/index.js` (npm link),
+  so a build changes what the service runs on its next restart.
 
 ## Run it against a dev stack
 

package/README-CLI.md

@@ -58,6 +58,9 @@ Commands:
   runner:start [options]                               Connect this machine's Ollama to the Lambforge chat as a local AI runner (outbound connection only - works behind NAT, Ollama is never exposed)
   runner:daemon:install|runner:start:daemon [options]  Run the runner in the background as a systemd user service: starts with your session, restarts on failure (Linux)
   runner:daemon:status [options]                       Show the runner service status (systemctl --user status)
+  runner:daemon:start [options]                        Start the installed runner service, and report whether it stays up
+  runner:daemon:stop [options]                         Stop the runner service (it stays installed and starts at your next login)
+  runner:daemon:restart [options]                      Restart the runner service (e.g. after `gcli login` to another server)
   runner:daemon:logs [options]                         Follow the runner service log (journalctl --user -f)
   runner:daemon:uninstall [options]                    Stop and remove the runner service (the runner stays registered)
   runner:list                                          List your local AI runners and the models they serve
@@ -66,6 +69,16 @@ Commands:
   workspace:start [options]                            Connect the current directory to the Lambforge chat as a local workspace: the AI agents can read/edit its files and run commands here (outbound connection only - works behind NAT)
   workspace:list [options]                             List your local workspaces (online status, directory, processes)
   workspace:delete [options]                           Delete a local workspace and revoke its token (default: the one registered for this directory)
+  workflow:list [options]                              List the project workflows
+  workflow:get [options]                               Print a workflow as YAML (the format workflow:apply reads), or write it with -o
+  workflow:generate [options]                          Draft a workflow with AI from plain language (or change one with --name / --from). Prints or writes YAML; saves only with --apply
+  workflow:apply [options]                             Create or update a workflow from a YAML/JSON file (workflow: {name, description, definition})
+  workflow:validate [options]                          Check a workflow file against the cluster (lambdas exist, graph is valid)
+  workflow:delete [options]                            Delete a workflow and all of its runs
+  workflow:run [options]                               Start a run; the JSON input is the first step request body. --wait follows it to the end
+  workflow:runs [options]                              List a workflow runs, newest first
+  workflow:status [options]                            Show a run: its step events, error and output (--follow until it ends)
+  workflow:cancel [options]                            Cancel a running run
   help [command]                                       display help for command
 
 --- Subcommand: login ---
@@ -879,6 +892,33 @@ Usage: gcli runner:daemon:status [options]
 
 Show the runner service status (systemctl --user status)
 
+Options:
+  --service <name>  systemd unit name (default: lambforge-runner)
+  -h, --help        display help for command
+
+--- Subcommand: runner:daemon:start ---
+Usage: gcli runner:daemon:start [options]
+
+Start the installed runner service, and report whether it stays up
+
+Options:
+  --service <name>  systemd unit name (default: lambforge-runner)
+  -h, --help        display help for command
+
+--- Subcommand: runner:daemon:stop ---
+Usage: gcli runner:daemon:stop [options]
+
+Stop the runner service (it stays installed and starts at your next login)
+
+Options:
+  --service <name>  systemd unit name (default: lambforge-runner)
+  -h, --help        display help for command
+
+--- Subcommand: runner:daemon:restart ---
+Usage: gcli runner:daemon:restart [options]
+
+Restart the runner service (e.g. after `gcli login` to another server)
+
 Options:
   --service <name>  systemd unit name (default: lambforge-runner)
   -h, --help        display help for command
@@ -979,3 +1019,118 @@ Delete a local workspace and revoke its token (default: the one registered for t
 Options:
   --id <id>   Workspace id (see `gcli workspace:list`)
   -h, --help  display help for command
+
+--- Subcommand: workflow:list ---
+Usage: gcli workflow:list [options]
+
+List the project workflows
+
+Options:
+  -p, --project <project>
+  -h, --help               display help for command
+
+--- Subcommand: workflow:get ---
+Usage: gcli workflow:get [options]
+
+Print a workflow as YAML (the format workflow:apply reads), or write it with -o
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Workflow name
+  -o, --out <file>         Write the YAML to this file
+  -h, --help               display help for command
+
+--- Subcommand: workflow:generate ---
+Usage: gcli workflow:generate [options]
+
+Draft a workflow with AI from plain language (or change one with --name / --from). Prints or writes YAML; saves only with --apply
+
+Options:
+  -p, --project <project>
+  -d, --description <text>  What the workflow should do, e.g. "charge the card
+                            with retries, then email the receipt"
+  -n, --name <name>         Workflow name: an existing one is changed, a new
+                            one is named so
+  --from <file>             Change this workflow file instead
+  -o, --out <file>          Write the draft YAML to this file
+  --apply                   Save the draft as the workflow (needs a name)
+  -h, --help                display help for command
+
+--- Subcommand: workflow:apply ---
+Usage: gcli workflow:apply [options]
+
+Create or update a workflow from a YAML/JSON file (workflow: {name, description, definition})
+
+Options:
+  -p, --project <project>
+  -f, --file <file>         Workflow file
+  -n, --name <name>         Overrides workflow.name from the file
+  -d, --description <text>  Overrides workflow.description
+  -h, --help                display help for command
+
+--- Subcommand: workflow:validate ---
+Usage: gcli workflow:validate [options]
+
+Check a workflow file against the cluster (lambdas exist, graph is valid)
+
+Options:
+  -p, --project <project>
+  -f, --file <file>        Workflow file
+  -h, --help               display help for command
+
+--- Subcommand: workflow:delete ---
+Usage: gcli workflow:delete [options]
+
+Delete a workflow and all of its runs
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Workflow name
+  -h, --help               display help for command
+
+--- Subcommand: workflow:run ---
+Usage: gcli workflow:run [options]
+
+Start a run; the JSON input is the first step request body. --wait follows it to the end
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Workflow name
+  -i, --input <json>       Run input as JSON (default {})
+  --input-file <file>      Read the run input from a JSON file
+  -w, --wait               Print each step as it happens until the run ends
+  -h, --help               display help for command
+
+--- Subcommand: workflow:runs ---
+Usage: gcli workflow:runs [options]
+
+List a workflow runs, newest first
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Workflow name
+  -l, --limit <limit>      How many (default 50)
+  -h, --help               display help for command
+
+--- Subcommand: workflow:status ---
+Usage: gcli workflow:status [options]
+
+Show a run: its step events, error and output (--follow until it ends)
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Workflow name
+  -r, --run <run>          Run name (see workflow:runs)
+  -f, --follow             Keep printing events until the run ends
+  -h, --help               display help for command
+
+--- Subcommand: workflow:cancel ---
+Usage: gcli workflow:cancel [options]
+
+Cancel a running run
+
+Options:
+  -p, --project <project>
+  -n, --name <name>        Workflow name
+  -r, --run <run>          Run name (see workflow:runs)
+  -h, --help               display help for command

package/README.md

@@ -761,6 +761,61 @@ gcli cron:list
 gcli cron:delete --lambdaName 'my-function'
 ```
 
+### Workflows
+
+A workflow runs several lambdas as one process: each step gets the previous
+step's response, steps can retry, branch (Choice), fan out (Parallel / Map)
+or wait, and every run is recorded step by step. Workflows must be included
+in the project's plan (`allowWorkflows`).
+
+```bash
+# Draft one with AI from plain language (MiniMax), review the YAML, save it
+gcli workflow:generate -d "charge the card with retries; if it fails wait 1h and email the customer; otherwise send the receipt" -o order-flow.yaml
+gcli workflow:apply -f order-flow.yaml --name order-flow     # create or update by name
+
+# Or change an existing one in place
+gcli workflow:generate --name order-flow -d "add a 5 minute wait before the email" --apply
+
+# Run it and watch each step
+gcli workflow:run --name order-flow --input '{"orderId": 42}' --wait
+gcli workflow:runs --name order-flow
+gcli workflow:status --name order-flow --run order-flow-abc12 --follow
+gcli workflow:cancel --name order-flow --run order-flow-abc12
+
+gcli workflow:list
+gcli workflow:get --name order-flow -o order-flow.yaml        # edit, then workflow:apply
+gcli workflow:validate -f order-flow.yaml
+gcli workflow:delete --name order-flow                        # also deletes its runs
+```
+
+The file `workflow:get` / `workflow:generate` write (and `workflow:apply`
+reads) - a Fission `kind: Workflow` manifest or a bare `startAt` + `states`
+works too:
+
+```yaml
+workflow:
+  name: order-flow
+  description: Charge, then mail the receipt
+  definition:
+    startAt: charge
+    states:
+      charge:
+        type: Task
+        function: { type: name, name: charge }
+        retry: { maxAttempts: 3, backoffBase: 2s, backoffCap: 30s }
+        next: mail
+      mail:
+        type: Task
+        function: { type: name, name: mailer }
+        end: true
+```
+
+Step types: Task (call a lambda), Choice (branch on a value), Parallel,
+Map (once per list item), Wait (durable pause), Succeed, Fail. A step gets
+one attempt unless it has `retry`. Runs can only be started by
+`workflow:run` (or the UI / API) - HTTP and cron triggers cannot start a
+workflow yet.
+
 ### Monitoring & Testing
 
 Debug your functions directly from the terminal.
@@ -890,7 +945,7 @@ running until Ctrl+C and reconnects on its own.
 | `gcli runner:list` | Your runners: online status, last seen, models |
 | `gcli runner:models` | List which models are shown in the chat; `--show a,b` shows only those, `--all` shows every model, `--none` hides them all; `--id` picks a runner (default: this machine's) |
 | `gcli runner:delete` | Delete a runner and revoke its token (`--id`, default: this machine's) |
-| `gcli runner:start:daemon` / `runner:daemon:install` | Install + start the runner as a systemd user service (Linux); `runner:daemon:status`, `runner:daemon:logs`, `runner:daemon:uninstall` manage it |
+| `gcli runner:start:daemon` / `runner:daemon:install` | Install + start the runner as a systemd user service (Linux); `runner:daemon:start`, `:stop`, `:restart`, `:status`, `:logs`, `:uninstall` manage it |
 
 ### Run it in the background (systemd, Linux)
 
@@ -899,6 +954,9 @@ npm i -g @gapi/gcli                 # a stable install - not the npx cache
 gcli login
 gcli runner:start:daemon            # = runner:daemon:install; same options as runner:start
 gcli runner:daemon:status
+gcli runner:daemon:stop             # stop it (stays installed, starts at next login)
+gcli runner:daemon:start            # start it again; tells you if it does not stay up
+gcli runner:daemon:restart          # e.g. after `gcli login` to another server
 gcli runner:daemon:logs             # follow the log (Ctrl+C to stop following)
 gcli runner:daemon:uninstall        # stop + remove the service (runner stays registered)
 ```

package/docs/changelog.d/2026-10-24-local-ai-runners-runner-daemon-start-stop-restart-and-start-reports-whether-t.md

@@ -0,0 +1,25 @@
+## 2026-10-24 - local-ai-runners: runner:daemon:start / stop / restart, and start reports whether the runner stays up
+
+**Feature:** local-ai-runners · **Type:** feat
+
+Why: after `runner:daemon:install` there was no gcli way to start or stop the service (only raw `systemctl --user`), and a service whose token Lambforge refuses failed silently: `runner:daemon:status` showed `status=78` with no explanation of what to do.
+
+- New commands (`src/commands/runner/index.ts`, `daemon-commands.ts`), all with `--service`:
+  - `runner:daemon:start` and `runner:daemon:restart` run `systemctl --user start/restart`. After ~2 s, `reportStarted` reads `ActiveState`/`ExecMainStatus` (`SystemdUserService.outcome`) and reports:
+    - running: says so;
+    - exit 78 (`RUNNER_AUTH_EXIT_CODE`): the token was refused - the runner was deleted, or registered on another server than `~/.graphql-server/url` - with the hint to re-register via `gcli runner:daemon:install --reset`;
+    - any other exit: points to `runner:daemon:logs`.
+  - `runner:daemon:stop`: `systemctl --user stop`. The unit stays enabled and starts at the next login; `uninstall` removes it.
+  - All three refuse with "not installed - run `gcli runner:daemon:install` first" when the unit file is missing.
+- `SystemdUserService`: `installed()`, `start()`, `stop()`, `restart()`, `outcome()`.
+- README, `README-CLI.md` (regenerated) and `docs/features/local-ai-runners.md` updated.
+- **Test:**
+  - `npx jest --coverage=false test/runner-daemon.spec.ts` covers: the systemctl calls, `installed()`, and the three `reportStarted` outcomes.
+  - Live: `gcli runner:daemon:stop`, `gcli runner:daemon:start`, then `gcli runner:daemon:status`.
+- **Debug:**
+  - "did not stay up": `gcli runner:daemon:logs`.
+  - "refused this runner's token": compare `~/.graphql-server/url` with the server the runner was registered on, then `runner:daemon:install --reset`.
+- **Verification:**
+  - jest: 11 suites, 103 tests pass (4 new). `tsc --noEmit` and eslint are clean.
+  - `npm run build`: `--help` lists the new commands.
+  - Not run against the real systemd unit.

package/docs/changelog.d/2026-10-25-workflows-workflow-commands-with-ai-drafts.md

@@ -0,0 +1,8 @@
+## 2026-10-25 - workflows: workflow commands with AI drafts
+
+**Feature:** workflows · **Type:** feat
+
+- New `workflow:*` commands (`src/commands/workflow/`): list, get (YAML), generate (AI draft via `generateWorkflowDraft`, from plain language or as a change to an existing workflow / file; `-o` writes YAML, `--apply` saves), apply (create or update by name), validate, delete, run (`--wait` prints each step event live until the run ends), runs, status (`--follow`), cancel. Workflows are addressed by name. Files: `workflow: {name, description, definition}`, a `kind: Workflow` manifest, or a bare definition. API in `gql-client.ts` (Workflows section), fragments in `services/types/workflow.fragment.ts`.
+- **Test:** `npx jest --coverage=false test/workflow.spec.ts` (file shapes, input parsing, event rendering, apply create/update, generate change + apply, run --wait).
+- **Debug:** see `docs/features/workflows.md`; the commands need a user login (not granted to CI tokens yet).
+- **Verification:** jest 6/6; tsc + eslint clean; build OK and `--help` lists the 10 commands (`release/index.js` restored, README-CLI.md regenerated); all 10 GraphQL documents validated against the live local gateway schema. Not run end to end here: the gcli login points at production, which has no workflows yet.

package/docs/features/README.md

@@ -35,3 +35,4 @@ Outline (drop sections that don't apply):
 | `lambforge-agent-skill` | [lambforge-agent-skill.md](lambforge-agent-skill.md) | The agent skill that teaches gcli + `mcp:start`; canonical doc in gql-fission |
 | `dedicated-platform-cluster` | [dedicated-platform-cluster.md](dedicated-platform-cluster.md) | `cluster:status/health/scale/autoscale/...` commands; canonical doc in lambforge-agent |
 | `ci-token-scopes` | [ci-token-scopes.md](ci-token-scopes.md) | Which permission each command needs; `mq-trigger:*` commands; canonical doc in graphql-server |
+| `workflows` | [workflows.md](workflows.md) | `workflow:*` commands incl. AI drafts (`workflow:generate`); canonical doc in graphql-server-lambdas |

package/docs/features/local-ai-runners.md

@@ -14,6 +14,8 @@ what lives in gcli.
 | `gcli runner:models [--id] [--show a,b \| --all \| --none]` | Which models appear in the chat picker; no flag = list |
 | `gcli runner:delete [--id]` | Delete a runner and revoke its token (default: the saved one) |
 | `gcli runner:daemon:install` (alias `runner:start:daemon`) `[runner:start options] [--service] [--dry-run]` | Resolve/register the runner now (saves `runner.json`), then install + enable + restart a systemd USER unit running `runner:start --ollama <resolved>` (Linux) |
+| `gcli runner:daemon:start` / `:restart` `[--service]` | `systemctl --user start/restart`, then after ~2 s reads `ActiveState`/`ExecMainStatus` (`SystemdUserService.outcome`): running, or an error - exit 78 = token refused (deleted, or registered on another server than `~/.graphql-server/url`) with the `runner:daemon:install --reset` hint. Refuses when the unit is not installed |
+| `gcli runner:daemon:stop` `[--service]` | `systemctl --user stop` (stays enabled: starts again at the next login) |
 | `gcli runner:daemon:status` / `:logs` / `:uninstall` | `systemctl --user status`, `journalctl --user -f`, disable --now + remove the unit |
 
 Endpoints: `--wsUrl` > `runner.json` > derived from the `gcli login` URL

package/docs/features/workflows.md

@@ -0,0 +1,49 @@
+# Workflows — gcli slice
+
+**Feature slug:** `workflows` · canonical doc:
+`graphql-server-lambdas/docs/features/workflows.md` (AI drafts:
+`graphql-server/docs/features/workflows.md`).
+
+`workflow:*` commands (`src/commands/workflow/`), all as the `gcli login`
+user through the gateway; workflows are addressed by **name** (resolved to
+the id with `listWorkflows`):
+
+| Command | API |
+|---|---|
+| `workflow:list` | `listWorkflows` |
+| `workflow:get -n [-o file]` | `listWorkflows` → YAML |
+| `workflow:generate -d "..." [-n name \| --from file] [-o file] [--apply]` | `generateWorkflowDraft` (graphql-server, MiniMax M3.1 Flash); `--apply` = `workflow:apply` |
+| `workflow:apply -f file [-n] [-d]` | `createWorkflow`, or `updateWorkflow` when the name exists |
+| `workflow:validate -f file` | `validateWorkflow` (graph + lambdas on the cluster) |
+| `workflow:delete -n` | `deleteWorkflow` (runs too) |
+| `workflow:run -n [-i json \| --input-file] [--wait]` | `startWorkflowRun`; `--wait` polls `getWorkflowRun` every 2 s and prints each new event until the run is terminal |
+| `workflow:runs -n [-l]` | `listWorkflowRuns` |
+| `workflow:status -n -r run [--follow]` | `getWorkflowRun` (events, error, output) |
+| `workflow:cancel -n -r run` | `cancelWorkflowRun` |
+
+The workflow file (`definition.ts` `parseWorkflowFile`) accepts
+`workflow: {name, description, clusterId, definition}`, the same without the
+`workflow:` key, a Fission `kind: Workflow` manifest, or a bare definition;
+`toWorkflowYaml` writes the first form. API calls are in
+`src/services/gql-client.ts` (Workflows section), selection sets in
+`src/services/types/workflow.fragment.ts`, types in
+`src/commands/workflow/types.ts`.
+
+Not granted to CI tokens (INTEGRATION role) yet: the workflow resolvers are
+USER-only in graphql-server-lambdas, so these commands need `gcli login`.
+
+## How to test
+
+`npx jest --coverage=false test/workflow.spec.ts`. Real: log in to a
+gateway whose project has `allowWorkflows`, then
+`gcli workflow:generate -d "..." -n demo --apply` and
+`gcli workflow:run -n demo --wait`.
+
+## How to debug
+
+- `No workflow "x"`: names are per project (`-p` or the `gcli login`
+  project).
+- `Workflows are not available on your current plan`: the plan lacks
+  `allowWorkflows`.
+- `Workflows are not enabled on this cluster`: the cluster runs Fission
+  without `workflows.enabled` (canonical doc, Requires).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gapi/gcli",
-  "version": "1.8.244",
+  "version": "1.8.246",
   "repository": {
     "type": "git",
     "url": "https://github.com/Stradivario/gapi.git"