@kody-ade/kody-engine 0.4.238 → 0.4.240

package/README.md

@@ -27,7 +27,7 @@ kody:  reads the issue → writes the code → runs your tests → opens a PR
 - **No infrastructure.** Runs on the GitHub Actions you already have. One ~20-line
   workflow file, installed via `npx`. Nothing to deploy or keep online.
 - **Whole PR lifecycle, not just authoring.** `run`, `resolve`, `sync`, `merge`,
-  `revert`, previews, releases, and scheduled duties — one executor, many verbs.
+  `revert`, previews, releases, and scheduled agentResponsibilities — one executor, many verbs.
 - **Declarative & extensible.** Every command is a folder of `profile.json` +
   `prompt.md` + shell. Add a command by dropping a folder — no engine changes.
 - **Bring your own model.** Anthropic native, or any provider via the built-in
@@ -74,19 +74,19 @@ See [SECURITY.md](SECURITY.md) to report a vulnerability.
 ┌─────────────────────────────────────────────┐
 │ kody-engine CLI (@kody-ade/kody-engine)    │
 │   bin/kody.ts — entrypoint                  │
-│   src/dispatch.ts — duty-driven routing     │
-│   src/executor.ts — runs duty implementations│
-│   .kody/duties/<slug>/                      │
-│     profile.json · duty.md                  │
-│   src/executables/<name>/                   │
+│   src/dispatch.ts — agentResponsibility-driven routing     │
+│   src/executor.ts — runs agentResponsibility implementations│
+│   .kody/agent-responsibilities/<slug>/                      │
+│     profile.json · agent-responsibility.md                  │
+│   src/agent-actions/<name>/                   │
 │     profile.json · prompt.md · *.sh         │
 │   src/scripts/*.ts — cross-cutting catalog  │
 └─────────────────────────────────────────────┘
 ```
 
-Every top-level command is an auto-discovered duty action. The router has **zero executable names hardcoded** — comment dispatch resolves the first token after `@kody` through `config.aliases`, then falls back to the legacy-named `config.defaultExecutable` / `config.defaultPrExecutable` fields as default duty actions. Drop a new `.kody/duties/<slug>/` directory with `profile.json` + `duty.md`; that duty chooses its implementation executable.
+Every top-level command is an auto-discovered agentResponsibility action. The router has **zero agentAction names hardcoded** — comment dispatch resolves the first token after `@kody` through `config.aliases`, then falls back to the legacy-named `config.defaultAgentAction` / `config.defaultPrAgentAction` fields as default agentResponsibility actions. Drop a new `.kody/agent-responsibilities/<slug>/` directory with `profile.json` + `agent-responsibility.md`; that agentResponsibility chooses its implementation agentAction.
 
-Executable directories are private implementation units and contain **only** three kinds of files: `profile.json` (declaration), `prompt.md` (agent instructions), and `.sh` scripts (mechanical side-effect work). Cross-cutting TypeScript lives in [src/scripts/](src/scripts/); it can't import from `src/executables/` and can't branch on `profile.name`.
+AgentAction directories are private implementation units and contain **only** three kinds of files: `profile.json` (declaration), `prompt.md` (agent instructions), and `.sh` scripts (mechanical side-effect work). Cross-cutting TypeScript lives in [src/scripts/](src/scripts/); it can't import from `src/agent-actions/` and can't branch on `profile.name`.
 
 ## Install in a consumer repo
 
@@ -94,7 +94,7 @@ Executable directories are private implementation units and contain **only** thr
 npx -y -p @kody-ade/kody-engine@latest kody-engine init
 ```
 
-`kody-engine init` scaffolds [kody.config.json](kody.config.schema.json), `.github/workflows/kody.yml` (generated from `WORKFLOW_TEMPLATE` in [src/scripts/initFlow.ts](src/scripts/initFlow.ts)), and per-scheduled-duty workflow files. Idempotent — pass `--force` to overwrite.
+`kody-engine init` scaffolds [kody.config.json](kody.config.schema.json), `.github/workflows/kody.yml` (generated from `WORKFLOW_TEMPLATE` in [src/scripts/initFlow.ts](src/scripts/initFlow.ts)), and per-scheduled-agentResponsibility workflow files. Idempotent — pass `--force` to overwrite.
 
 Required repo secrets: at least one model provider key (e.g. `MINIMAX_API_KEY`, `ANTHROPIC_API_KEY`). Recommended: `KODY_TOKEN` PAT so kody's commits trigger downstream CI and can modify `.github/workflows/*`.
 
@@ -123,10 +123,10 @@ kody-engine release-publish   --issue <N> [--dry-run]
 kody-engine release-deploy    --issue <N> [--dry-run]
 kody-engine npm-publish       [--tag latest] [--access public] [--dry-run]
 
-# scheduled duties and goals
-kody-engine duty-scheduler                                    # fan out due .kody/duties/<slug>/ folders
-kody-engine duty-tick          --duty <slug> [--force]        # one agent tick for one duty
-kody-engine duty-tick-scripted --duty <slug> [--force]        # one deterministic tickScript duty tick
+# scheduled agentResponsibilities and goals
+kody-engine agent-responsibility-scheduler                                    # fan out due .kody/agent-responsibilities/<slug>/ folders
+kody-engine agent-responsibility-tick          --agentResponsibility <slug> [--force]        # one agent tick for one agentResponsibility
+kody-engine agent-responsibility-tick-scripted --agentResponsibility <slug> [--force]        # one deterministic tickScript agentResponsibility tick
 kody-engine goal-scheduler                                    # fan out active .kody/goals/instances/* state files
 kody-engine goal-manager      --goal <id>                     # advance one managed goal instance
 
@@ -138,15 +138,15 @@ kody-engine serve                                             # LiteLLM/editor h
 kody-engine brain-serve                                       # Brain SSE server
 kody-engine pool-serve                                        # warm-pool owner
 kody-engine runner-serve                                      # warm-pool one-shot runner
-kody-engine worker-ask        --worker <slug> --message "..." # ad-hoc staff persona run
+kody-engine agent-ask        --agent <slug> --message "..." # ad-hoc agent run
 kody-engine stats                                             # inspect run/event history
 ```
 
-### Duties
+### AgentResponsibilities
 
-A **duty** is a folder at `.kody/duties/<slug>/` with `profile.json` metadata (`every`, `staff`, `action`, `executable`, `stage`, and related fields) plus human-owned prose in `duty.md`. `duty-scheduler` wakes on cron, finds due duties, and dispatches either `duty-tick` for an agent tick or `duty-tick-scripted` for a deterministic `tickScript` duty. `kody-engine init` copies built-in starter duties and scaffolds `.kody/staff/kody.md`.
+A **agentResponsibility** is a folder at `.kody/agent-responsibilities/<slug>/` with `profile.json` metadata (`every`, `agent`, `action`, `agentAction`, `stage`, and related fields) plus human-owned prose in `agent-responsibility.md`. `agent-responsibility-scheduler` wakes on cron, finds due agentResponsibilities, and dispatches either `agent-responsibility-tick` for an agent tick or `agent-responsibility-tick-scripted` for a deterministic `tickScript` agentResponsibility. `kody-engine init` copies built-in starter agentResponsibilities and scaffolds `.kody/agents/kody.md`.
 
-Locked-toolbox duties can declare `"tools": [...]` in `profile.json` to run with only the named high-level MCP intents plus `submit_state`; duties without `tools` keep the legacy Bash/gh toolbox.
+Locked-toolbox agentResponsibilities can declare `"tools": [...]` in `profile.json` to run with only the named high-level MCP intents plus `submit_state`; agentResponsibilities without `tools` keep the legacy Bash/gh toolbox.
 
 ### `release`
 
@@ -154,7 +154,7 @@ Locked-toolbox duties can declare `"tools": [...]` in `profile.json` to run with
 
 ## Profiles
 
-A profile is declarative JSON + an adjacent `prompt.md`. See any directory under [src/executables/](src/executables/) for examples. Adding a new command = new directory + profile + prompt + any `.sh` scripts + registering any new shared TS utilities under [src/scripts/](src/scripts/). No executor, entry, or dispatch changes.
+A profile is declarative JSON + an adjacent `prompt.md`. See any directory under [src/agent-actions/](src/agent-actions/) for examples. Adding a new command = new directory + profile + prompt + any `.sh` scripts + registering any new shared TS utilities under [src/scripts/](src/scripts/). No executor, entry, or dispatch changes.
 
 See [AGENTS.md](AGENTS.md) for the full architectural contract.
 

package/dist/{executables → agent-actions}/types.ts

@@ -1,5 +1,5 @@
 /**
- * Types shared by the generic executor and executables.
+ * Types shared by the generic executor and agentActions.
  *
  * The executor reads a Profile, validates the user's CLI args against
  * Profile.inputs, then runs the declared preflight scripts → agent →
@@ -20,49 +20,49 @@ export type CapabilityKind = "observe" | "act" | "verify"
 export interface Profile {
   name: string
   /**
-   * Public action name owned by a duty. A user may type `@kody <action>`;
-   * dispatch resolves that action to the duty, then the duty selects the
-   * implementation executable. Absent → the duty slug/name is the action.
+   * Public action name owned by a agentResponsibility. A user may type `@kody <action>`;
+   * dispatch resolves that action to the agentResponsibility, then the agentResponsibility selects the
+   * implementation agentAction. Absent → the agentResponsibility slug/name is the action.
    */
   action?: string
   /**
-   * Optional agent this executable runs *as*. When set, the executor
+   * Optional agent this agentAction runs *as*. When set, the executor
    * loads `.kody/agents/<agent>.md` and injects that agent (authoritative
-   * identity) ahead of the executable's own system-prompt append. This is the
-   * unification hook: a "duty" is just an executable + an agent. Absent →
+   * identity) ahead of the agentAction's own system-prompt append. This is the
+   * unification hook: a "agentResponsibility" is just an agentAction + an agent. Absent →
    * runs with no agent (unchanged legacy behaviour). A declared-but-missing
    * agent file is fatal at run time (see src/agents.ts).
    */
   agent?: string
   describe: string
   /**
-   * Author-facing capability promise for a duty/executable. This classifies the
+   * Author-facing capability promise for a agentResponsibility/agentAction. This classifies the
    * shape of result it should return; it does not change executor control flow.
    */
   capabilityKind?: CapabilityKind
   /**
-   * Semantic role — what this executable IS, not when it runs.
+   * Semantic role — what this agentAction IS, not when it runs.
    *   - primitive:    single-step agent executor (flow → agent → verify → commit → PR).
    *   - orchestrator: no-agent, drives primitives via a postflight transition table
    *                   (comment-based, one GHA run per step).
    *   - container:    no-agent, runs declared `children` sequentially in-process
    *                   (one GHA run for the whole flow). Routing is done by per-child
    *                   `next` maps over action types — no @kody comments dispatched.
-   *   - watch:        scheduled observer that inspects repo state and may trigger other executables.
+   *   - watch:        scheduled observer that inspects repo state and may trigger other agentActions.
    *   - utility:      no-agent, one-off administrative work (scaffolding, release, etc.).
    *
    * Roles enforce shape at profile-load time and let help/dispatch treat
-   * executables differently by category.
+   * agentActions differently by category.
    */
   role: "primitive" | "orchestrator" | "container" | "watch" | "utility"
   /**
-   * A duty is the WHY/WHEN layer: it references an executable (the HOW) by name
-   * rather than embedding it. When set, the loader resolves that executable's
-   * full profile (claudeCode/scripts/prompt/agents) and overlays this duty's
+   * A agentResponsibility is the WHY/WHEN layer: it references an agentAction (the HOW) by name
+   * rather than embedding it. When set, the loader resolves that agentAction's
+   * full profile (claudeCode/scripts/prompt/agents) and overlays this agentResponsibility's
    * name + agent (WHO) + every (WHEN) + mentions. Absent → this profile IS an
-   * executable (defines its own how). executable = how, agent = who, duty = why.
+   * agentAction (defines its own how). agentAction = how, agent = who, agentResponsibility = why.
    */
-  executable?: string
+  agentAction?: string
   /**
    * Execution model — orthogonal to `role`.
    * `oneshot` (default): single invocation on demand.
@@ -71,31 +71,31 @@ export interface Profile {
    */
   kind: "oneshot" | "scheduled"
   /**
-   * Recurrence cadence for a duty that runs on a timer (unified successor to a
-   * markdown duty's `every:` metadata). One of the ScheduleEvery values
-   * ("15m".."7d" | "manual"). Present → the duty-scheduler fires a one-shot run
+   * Recurrence cadence for a agentResponsibility that runs on a timer (unified successor to a
+   * markdown agentResponsibility's `every:` metadata). One of the ScheduleEvery values
+   * ("15m".."7d" | "manual"). Present → the agent-responsibility-scheduler fires a one-shot run
    * when due (no target). Absent → on-demand only (runs against an issue/PR).
-   * This is what makes "scheduled" just a field on the one duty shape.
+   * This is what makes "scheduled" just a field on the one agentResponsibility shape.
    */
   every?: string
   /**
-   * Locked-toolbox palette (unified successor to a markdown duty's `tools:`
-   * metadata). When non-empty, loadDutyState sets ctx.data.dutyTools so the
-   * executor spins up the in-process kody-duty MCP server and the agent runs
+   * Locked-toolbox palette (unified successor to a markdown agentResponsibility's `tools:`
+   * metadata). When non-empty, loadAgentResponsibilityState sets ctx.data.agentResponsibilityTools so the
+   * executor spins up the in-process kody-agentResponsibility MCP server and the agent runs
    * MCP-only (Bash/Read revoked unless also in claudeCode.tools). Absent →
    * normal SDK tools.
    */
-  dutyTools?: string[]
+  agentResponsibilityTools?: string[]
   /**
-   * GitHub logins (no leading `@`) this duty's output should mention. Rendered
-   * to `@a @b` and exposed to the prompt as {{mentions}} (and as the duty-MCP
-   * operator mention), mirroring a markdown duty's `mentions:` metadata.
+   * GitHub logins (no leading `@`) this agentResponsibility's output should mention. Rendered
+   * to `@a @b` and exposed to the prompt as {{mentions}} (and as the agentResponsibility-MCP
+   * operator mention), mirroring a markdown agentResponsibility's `mentions:` metadata.
    */
   mentions?: string[]
   /** Cron expression for scheduled profiles (e.g. "0 8 * * MON"). */
   schedule?: string
   /**
-   * Task-state phase label emitted when this executable completes successfully.
+   * Task-state phase label emitted when this agentAction completes successfully.
    * Failing actions always set phase to "failed" regardless. Omitted → "idle".
    * Lets state.ts stay generic — phase semantics live on the profile.
    */
@@ -111,7 +111,7 @@ export interface Profile {
    *
    * Lifecycles exist to consolidate orchestration boilerplate (label,
    * context loading, verify, commit, comment) that recurs across many
-   * executables. Per-executable specifics still go in `scripts.preflight`
+   * agentActions. Per-agentAction specifics still go in `scripts.preflight`
    * and `scripts.postflight` — the lifecycle wraps them, it doesn't
    * replace them.
    */
@@ -127,14 +127,14 @@ export interface Profile {
   }
   outputContract?: OutputContract
   /**
-   * Declared artifacts consumed by this executable. The resolveArtifacts
+   * Declared artifacts consumed by this agentAction. The resolveArtifacts
    * preflight loads each into ctx.data.artifacts[name] from the task-state
-   * comment. If `required: true` and the artifact is absent, the executable
+   * comment. If `required: true` and the artifact is absent, the agentAction
    * fails fast.
    */
   inputArtifacts: InputArtifactSpec[]
   /**
-   * Declared artifacts produced by this executable. The persistArtifacts
+   * Declared artifacts produced by this agentAction. The persistArtifacts
    * postflight reads the named source field from ctx.data and writes an
    * Artifact entry into the task-state comment's `artifacts` map.
    */
@@ -175,16 +175,16 @@ export interface Profile {
    * preflight runs. composePrompt prefers these over a fresh disk read so the
    * template survives working-tree churn from runFlow's branch setup — on the CI
    * runner a branch checkout can drop the tracked-but-ignore-negated
-   * `.kody/executables/<name>/` dir, and reading prompt.md afterwards fails with
+   * `.kody/agent-actions/<name>/` dir, and reading prompt.md afterwards fails with
    * ENOENT even though profile.json (read here, earlier) loaded fine.
    */
   promptTemplates?: Record<string, string>
   /**
    * Subagent markdown captured (by declared name) at load time, BEFORE any
    * task branch switch — same rationale as promptTemplates. loadSubagents
-   * prefers this snapshot so a duty's `agents/` surviving only on the default
-   * checkout (e.g. `.kody/duties/<slug>/agents/` absent on a PR branch) doesn't
-   * crash a PR-targeted duty. Populated by captureSubagentTemplates.
+   * prefers this snapshot so a agentResponsibility's `agents/` surviving only on the default
+   * checkout (e.g. `.kody/agent-responsibilities/<slug>/agents/` absent on a PR branch) doesn't
+   * crash a PR-targeted agentResponsibility. Populated by captureSubagentTemplates.
    */
   subagentTemplates?: Record<string, string>
 }
@@ -200,7 +200,7 @@ export interface Profile {
  *   - no match → container aborts
  */
 export interface ContainerChild {
-  /** Name of the executable to invoke (must resolve via the registry). */
+  /** Name of the agentAction to invoke (must resolve via the registry). */
   exec: string
   /**
    * Where to source the target identifier from when invoking this child.
@@ -221,7 +221,7 @@ export interface ContainerChild {
 export interface InputArtifactSpec {
   /** Artifact name (the key in state.artifacts). */
   name: string
-  /** If true, the executable fails when this artifact is missing from state. */
+  /** If true, the agentAction fails when this artifact is missing from state. */
   required?: boolean
 }
 
@@ -302,7 +302,7 @@ export interface ClaudeCodeSpec {
   /**
    * Opt-in: expose an in-process `submit_state` tool the agent calls to
    * persist its next state, instead of relying on a trailing fenced
-   * `kody-job-next-state` block it must remember to emit. Used by duty-tick.
+   * `kody-job-next-state` block it must remember to emit. Used by agent-responsibility-tick.
    * The fenced block stays supported as a fallback. Default false.
    */
   enableSubmitTool?: boolean
@@ -312,7 +312,7 @@ export interface ClaudeCodeSpec {
    * first attempt). Set to 0 or omit to use the default.
    */
   verifyAttempts?: number | null
-  /** SDK built-in tools this executable is allowed to use (capability pack). */
+  /** SDK built-in tools this agentAction is allowed to use (capability pack). */
   tools: string[]
   /**
    * Names of bundled hook configs to load (from src/plugins/hooks/<name>.json).
@@ -360,7 +360,7 @@ export interface ScriptEntry {
    */
   script?: string
   /**
-   * Filename of a shell script colocated with the executable
+   * Filename of a shell script colocated with the agentAction
    * (e.g. "apply-prefer.sh"). Resolved relative to the profile's
    * directory. Invoked via `bash <path> <with-args>` with ctx.args
    * exposed as env vars (KODY_ARG_<UPPER_NAME>=<value>). A stdout
@@ -477,11 +477,11 @@ export interface Context {
      * `@kody <next>` comment, which is silently ignored when Kody comments as
      * a GitHub App (bot author), stalling the pipeline at classify.
      */
-    nextDispatch?: { action?: string; duty?: string; executable?: string; cliArgs: Record<string, unknown> }
+    nextDispatch?: { action?: string; agentResponsibility?: string; agentAction?: string; cliArgs: Record<string, unknown> }
     /** In-process hand-off to a full Job, preserving job identity in task state. */
     nextJob?: Job
     /** Where to return after nextJob succeeds. Used by task-jobs to keep draining pending work. */
-    afterNextJob?: { action?: string; duty?: string; executable?: string; cliArgs: Record<string, unknown> }
+    afterNextJob?: { action?: string; agentResponsibility?: string; agentAction?: string; cliArgs: Record<string, unknown> }
   }
   /**
    * If a preflight script sets this to true, the executor skips the agent
@@ -513,26 +513,26 @@ export type AnyScript = PreflightScript | PostflightScript
 // Job — the unified work request (task-state jobs collect run attempts).
 //
 // A Job is the required work the engine tries to execute, regardless of how it
-// was triggered. It must reference a duty/action (why). The executable is only
-// the duty-selected implementation detail (how), never a standalone request.
+// was triggered. It must reference a agentResponsibility/action (why). The agentAction is only
+// the agentResponsibility-selected implementation detail (how), never a standalone request.
 // Task state stores this durable job separately from individual run attempts.
 // Two flavors:
 //   - "instant"   — run once now (an `@kody <verb>` comment or a manual dispatch)
 //   - "scheduled" — fired on `schedule` (cron) by the tick path
 //
 // `runJob` (src/job.ts) lowers a Job onto the private executor after resolving
-// the duty, and seeds both stable job metadata and per-run metadata.
+// the agentResponsibility, and seeds both stable job metadata and per-run metadata.
 // ────────────────────────────────────────────────────────────────────────────
 
 export type JobFlavor = "instant" | "scheduled"
 
 export interface Job {
-  /** Public action the user/operator invoked. Mirrors the duty action. */
+  /** Public action the user/operator invoked. Mirrors the agentResponsibility action. */
   action?: string
-  /** How: implementation profile selected by the duty. Not valid by itself. */
-  executable?: string
-  /** Why (referenced): a duty slug whose intent drives the run. */
-  duty?: string
+  /** How: implementation profile selected by the agentResponsibility. Not valid by itself. */
+  agentAction?: string
+  /** Why (referenced): a agentResponsibility slug whose intent drives the run. */
+  agentResponsibility?: string
   /** Why (inline): free-text intent, e.g. an `@kody` comment body. Untrusted —
    *  fenced where it enters a prompt, not here. */
   why?: string
@@ -542,7 +542,7 @@ export interface Job {
   schedule?: string
   /** The issue/PR number this job acts on, when applicable. */
   target?: number
-  /** Args passed through to the executable (mirrors DispatchResult.cliArgs). */
+  /** Args passed through to the agentAction (mirrors DispatchResult.cliArgs). */
   cliArgs: Record<string, unknown>
   /** Run once now ("instant") or on the schedule ("scheduled"). */
   flavor: JobFlavor

package/dist/agent-responsibilities/run/agent-responsibility.md

@@ -0,0 +1,10 @@
+# Run
+
+## Purpose
+
+Implement a GitHub issue end-to-end.
+
+## Instructions
+
+Use the `run` agentAction for the implementation details.
+The agentResponsibility owns the public action name and the reason this action exists; the agentAction owns the method.

package/dist/{duties → agent-responsibilities}/run/profile.json

@@ -1,6 +1,6 @@
 {
   "name": "run",
   "action": "run",
-  "executable": "run",
+  "agentAction": "run",
   "describe": "Implement a GitHub issue end-to-end."
 }