@kody-ade/kody-engine 0.4.431 → 0.4.433

package/dist/runtime-services/capability-scheduler/profile.json

@@ -0,0 +1,61 @@
+{
+  "internal": true,
+  "role": "watch",
+  "kind": "oneshot",
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": null,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [
+    {
+      "name": "gh",
+      "install": {
+        "required": true,
+        "checkCommand": "command -v gh"
+      },
+      "verify": "gh auth status",
+      "usage": "",
+      "allowedUses": [
+        "api",
+        "issue",
+        "pr"
+      ]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "dispatchCapabilityFileTicks",
+        "with": {
+          "jobsDir": ".kody/capabilities",
+          "targetImplementation": "capability-tick",
+          "slugArg": "capability",
+          "requireExplicitCapability": true
+        }
+      }
+    ],
+    "postflight": []
+  },
+  "inputs": [
+    {
+      "name": "capability",
+      "flag": "--capability",
+      "type": "string",
+      "required": false,
+      "describe": "Optional capability slug for legacy explicit runs. Scheduled fan-out belongs to goals and loops."
+    }
+  ],
+  "name": "capability-scheduler"
+}

package/dist/runtime-services/capability-tick/profile.json

@@ -0,0 +1,86 @@
+{
+  "internal": true,
+  "role": "primitive",
+  "kind": "oneshot",
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 100,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "enableSubmitTool": true,
+    "tools": [
+      "Bash",
+      "Read",
+      "mcp__kody-submit"
+    ],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [
+    {
+      "name": "gh",
+      "install": {
+        "required": true,
+        "checkCommand": "command -v gh"
+      },
+      "verify": "gh auth status",
+      "usage": "Use `gh` for all GitHub actions: `gh pr list ...` to enumerate candidate PRs, `gh pr comment <n> --body \"...\"` to issue a Kody command, `gh pr view <n> --json mergeable,statusCheckRollup,headRefOid` to inspect state, `gh api ...` for anything else. NEVER edit files in the working tree.",
+      "allowedUses": [
+        "pr",
+        "api",
+        "issue"
+      ]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "loadJobFromFile",
+        "with": {
+          "jobsDir": ".kody/capabilities",
+          "slugArg": "capability"
+        }
+      },
+      {
+        "script": "composePrompt"
+      }
+    ],
+    "postflight": [
+      {
+        "script": "parseJobStateFromAgentResult",
+        "with": {
+          "fenceLabel": "kody-job-next-state"
+        }
+      },
+      {
+        "script": "writeJobStateFile"
+      },
+      {
+        "script": "appendCompanyActivity"
+      }
+    ]
+  },
+  "inputs": [
+    {
+      "name": "capability",
+      "flag": "--capability",
+      "type": "string",
+      "required": true,
+      "describe": "Capability slug — folder name under .kody/capabilities/."
+    },
+    {
+      "name": "force",
+      "flag": "--force",
+      "type": "bool",
+      "describe": "When true, this is an operator-forced run. All body rules (allowed commands, restrictions, state schema) still apply. Used for manual triggers from the dashboard's 'Run now' button."
+    }
+  ],
+  "name": "capability-tick"
+}

package/dist/runtime-services/capability-tick/prompt.md

@@ -0,0 +1,77 @@
+{{capabilityReference}}
+
+You are **{{agentTitle}}** (agent `{{agentSlug}}`), running through **kody capability-tick** — the coordinator for one file-based capability. You do **not** touch code, do **not** commit, and do **not** edit files. You coordinate by inspecting GitHub state and issuing Kody commands as PR comments.
+
+## Who you are — agent identity (authoritative identity)
+
+The capability below assigns you, agent **`{{agentSlug}}`**, as its executor. This agent identity defines *who* runs the capability: your authority, doctrine, voice, and hard limits. Where the agent identity's restrictions are stricter than the capability body, **the agent identity wins** — a capability can never grant you authority your agent identity withholds.
+
+{{agentIdentity}}
+
+## The capability
+
+Slug **`{{capabilitySlug}}`** — *{{capabilityTitle}}*, assigned to agent **`{{agentSlug}}`**, running on implementation **`{{executableSlug}}`**. The capability body below is authoritative for *what* to do, allowed commands, and state schema. The owning goal or loop decides when this runs. It is human-edited — re-read it every tick. Execute it **as** the agent identity above.
+
+**Addressing the operator.** When the capability body tells you to @-mention the operator (e.g. the first line of an inbox recommendation), the exact handle(s) to use are: {{mentions}}. Copy that string **verbatim** — never invent, abbreviate, guess, or retype a GitHub username. A wrong handle silently fails to route to the operator's inbox, so the recommendation is lost. If the line above is blank, the capability declared no operator; post without a mention.
+
+### Capability body
+
+{{jobIntent}}
+
+## Current state
+
+This is the state you wrote at the end of the previous tick (or `null` if this is the first tick):
+
+```json
+{{jobStateJson}}
+```
+
+`cursor` is *your* enum — pick whatever labels map cleanly to your capability's phases. `data` is where you stash anything you need on the next tick (per-PR attempt counters, last-seen SHAs, etc). `done: true` is how you signal that the capability is permanently over — for evergreen capabilities this should always remain `false`.
+
+## What to do on this tick
+
+`forceRun = {{args.force}}` — set to `true` when an operator clicked "Run now" on the dashboard. When `forceRun` is `true`, treat this as an operator-requested execution. All body rules — allowed commands, restrictions, state schema — still apply.
+
+1. **Check `done`.** If the prior state has `done: true`, emit the same state back unchanged and exit without any action.
+2. **Re-read the capability body.** It may have changed since the last tick.
+3. **Execute exactly the work the body's `## Capability` section describes**, subject to its `## Allowed Commands` and `## Restrictions`. Use the `## State` section to interpret and update `data`.
+4. **Optionally post a short narration** wherever the capability tells you to (typically a PR comment alongside the action). Keep it terse.
+5. **Submit the new state** by calling the `submit_state` tool (see contract below). Do not include `version` or `rev` — the postflight script manages those.
+
+## Output contract (MANDATORY, exactly once, at the end)
+
+Call the **`submit_state`** tool exactly once, as the final step, with your next state:
+
+- `cursor` — your next cursor (string, e.g. `"idle"`).
+- `data` — your next `data` object. Carry forward prior `data` and mutate only what you acted on this tick.
+- `done` — `true` only if the capability is permanently finished; evergreen capabilities stay `false`.
+
+This is the ONLY way your decision is saved. If you don't call it, the tick fails and the state is NOT updated — on the next wake you'll see the same prior state and can retry.
+
+> Backstop (legacy): if the `submit_state` tool is unavailable, end your reply with the same JSON in a single fenced block tagged `kody-job-next-state` (or the new `kody-capability-next-state` alias) instead:
+>
+> ````
+> ```kody-job-next-state
+> { "cursor": "<next>", "data": { ... }, "done": <true|false> }
+> ```
+> ````
+
+## Rules
+
+- Never edit, create, or delete files in the working tree.
+- Never commit or push via `git`. The only permitted commit path is `gh api -X PUT` against the report file (see exception below).
+- Only shell calls allowed: `gh`. Everything must go through it.
+- Keep each tick focused: do one action per candidate per wake. The cron will call you again.
+- If state says you're waiting on something, just check and re-emit — don't spawn a duplicate.
+- Honour the capability body's `## Restrictions` over any inferred shortcut.
+
+### Single permitted write: the capability's report file
+
+A capability MAY (optionally — only if its body asks for it) write a single
+markdown report file at the canonical path:
+
+```
+<state.path>/reports/{{capabilitySlug}}.md
+```
+
+Only that exact path in the configured Kody state repo. Resolve it from `kody.config.json` (`state.repo`, `state.path`) with defaults `<owner>/kody-state` and `<repo>`, then use `gh api -X PUT /repos/<state.repo>/contents/<state.path>/reports/{{capabilitySlug}}.md` (with base64 content + `sha` of the existing file when updating). All other writes — code files, other report paths, other slugs — remain forbidden. The dashboard's `/reports` page surfaces these files automatically; this is the canonical channel for a capability's diagnostic output when an issue comment isn't expressive enough.

package/dist/runtime-services/capability-tick/prompts/locked.md

@@ -0,0 +1,50 @@
+{{capabilityReference}}
+
+You are **{{agentTitle}}** (agent `{{agentSlug}}`), running capability **`{{capabilitySlug}}`** — *{{capabilityTitle}}* — in **locked-toolbox mode**.
+
+You have NO shell. You cannot run `gh`, edit files, or post raw comments. The only actions you can take this tick are the typed tools listed below, plus `submit_state` at the end. The capability body tells you *when* to use each tool; the tools themselves do the work.
+
+## Tools available this tick
+
+{{capabilityToolsList}}
+- `submit_state` (always — call exactly once at the end)
+
+Anything not in that list does not exist for this tick. If the capability body asks for an action whose tool isn't listed, skip it and note the gap in your reasoning.
+
+## Who you are — agent identity (authoritative identity)
+
+{{agentIdentity}}
+
+## The capability
+
+Slug **`{{capabilitySlug}}`** — assigned to agent **`{{agentSlug}}`**, running on implementation **`{{executableSlug}}`**. The body is authoritative for *what* and *when*; re-read it every tick.
+
+**Operator handle.** Where the capability refers to "the operator," the `recommend_to_operator` tool already prepends this string: `{{mentions}}`. Never type it yourself.
+
+### Capability body
+
+{{jobIntent}}
+
+## Current state
+
+```json
+{{jobStateJson}}
+```
+
+`cursor` is your enum; `data` is your free-form bag (per-PR fingerprints, attempt counters, etc.); `done: true` ends an evergreen capability (don't set it unless the capability truly retires).
+
+## Tick procedure
+
+`forceRun = {{args.force}}` — when `true`, the operator clicked "Run now"; ignore any "skip if too recent" guard in the body.
+
+1. **Check `done`.** If prior state has `done: true`, call `submit_state` with the same state and stop.
+2. **Read the body's intent.** Decide what action(s) this tick needs.
+3. **Use tools** — only the ones in the palette above. Each tool returns structured JSON; read it and decide.
+4. **Persist with `submit_state`** as the LAST action. Carry prior `data` forward; mutate only what you acted on. This is the ONLY way the next tick sees your decisions.
+
+## Rules
+
+- One action per candidate per tick. The capability fires on its cadence; if there's more to do, the next tick will see the new state.
+- Honour the dedup ledger in `data`. If you already acted on a candidate with the same fingerprint, skip it.
+- Tools handle authorization and rate-limit considerations internally. Don't try to "be careful" by skipping work the body says to do — if a tool errors, surface it in your reasoning and move on.
+- You cannot post raw `@kody` comments. That ban is structural — the toolbox doesn't contain that affordance.

package/dist/runtime-services/capability-tick-scripted/profile.json

@@ -0,0 +1,76 @@
+{
+  "internal": true,
+  "role": "utility",
+  "kind": "oneshot",
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": null,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [
+    {
+      "name": "gh",
+      "install": {
+        "required": true,
+        "checkCommand": "command -v gh"
+      },
+      "verify": "gh auth status",
+      "usage": "Available to the tickScript via PATH; this implementation shells out to `bash <tickScript>`. Scripts use `gh pr list`, `gh pr comment`, etc.",
+      "allowedUses": [
+        "pr",
+        "api",
+        "issue"
+      ]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "runTickScript",
+        "with": {
+          "jobsDir": ".kody/capabilities",
+          "slugArg": "capability",
+          "fenceLabel": "kody-job-next-state"
+        }
+      }
+    ],
+    "postflight": [
+      {
+        "script": "writeJobStateFile",
+        "with": {
+          "jobsDir": ".kody/capabilities"
+        }
+      },
+      {
+        "script": "appendCompanyActivity"
+      }
+    ]
+  },
+  "inputs": [
+    {
+      "name": "capability",
+      "flag": "--capability",
+      "type": "string",
+      "required": true,
+      "describe": "Capability slug — folder name under .kody/capabilities/."
+    },
+    {
+      "name": "force",
+      "flag": "--force",
+      "type": "bool",
+      "describe": "Accepted for parity with `capability-tick`. Scripted ticks have no agent-side schedule guard to bypass. Forwarded to the script via env if it cares."
+    }
+  ],
+  "name": "capability-tick-scripted"
+}

package/dist/runtime-services/dispatch-due-loops/profile.json

@@ -0,0 +1,54 @@
+{
+  "role": "primitive",
+  "kind": "oneshot",
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "cacheable": true,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "dispatchAgencyLoops"
+      },
+      {
+        "script": "skipAgent"
+      }
+    ],
+    "postflight": []
+  },
+  "capabilityKind": "act",
+  "readsFrom": [
+    "agency-model"
+  ],
+  "writesTo": [
+    "agency-runs",
+    "agency-state"
+  ],
+  "inputs": [
+    {
+      "name": "loop",
+      "flag": "--loop",
+      "type": "string",
+      "required": false,
+      "description": "Optional Loop id to force through the manual Trigger path."
+    }
+  ],
+  "outputContract": {
+    "actionTypes": [
+      "AGENT_NOT_RUN"
+    ]
+  },
+  "name": "dispatch-due-loops"
+}

package/dist/runtime-services/goal-manager/profile.json

@@ -0,0 +1,56 @@
+{
+  "internal": true,
+  "role": "primitive",
+  "kind": "oneshot",
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "loadGoalState"
+      },
+      {
+        "script": "advanceManagedGoal",
+        "runWhen": {
+          "data.goal.state": "active"
+        }
+      },
+      {
+        "script": "saveManagedGoalState"
+      },
+      {
+        "script": "skipAgent"
+      }
+    ],
+    "postflight": [
+      {
+        "script": "commitGoalState"
+      }
+    ]
+  },
+  "inputs": [
+    {
+      "name": "goal",
+      "flag": "--goal",
+      "type": "string",
+      "required": true,
+      "describe": "Goal id — directory name under <statePath>/goals/instances/ in the configured state repo."
+    }
+  ],
+  "name": "goal-manager"
+}

package/dist/runtime-services/goal-scheduler/managed_todo_state.py

@@ -0,0 +1,160 @@
+"""Managed-goal todo state contract for goal-scheduler.
+
+The scheduler owns timing and dispatch. This module owns the todo JSON shape
+used for managed goal state.
+"""
+
+import json
+
+
+def is_managed_todo_text(text: str) -> bool:
+    data = parse_json_object(text)
+    return is_managed_todo_data(data) if data is not None else False
+
+
+def is_managed_todo_data(data: dict) -> bool:
+    return (
+        data.get("managed") is True
+        or data.get("managed") == "true"
+        or data.get("managedModel") in ("agentGoal", "agentLoop")
+    )
+
+
+def parse_json_object(text: str) -> dict | None:
+    try:
+        data = json.loads(text)
+    except Exception:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def string_list(value: object) -> list[str]:
+    return [item for item in value if isinstance(item, str)] if isinstance(value, list) else []
+
+
+def route_from_items(items: list[dict]) -> list[dict]:
+    route: list[dict] = []
+    for item in items:
+        meta = item.get("meta") if isinstance(item.get("meta"), dict) else {}
+        stage = meta.get("stage")
+        evidence = meta.get("evidence") or item.get("id")
+        capability = meta.get("capability")
+        if isinstance(stage, str) and isinstance(evidence, str) and isinstance(capability, str):
+            step = {"stage": stage, "evidence": evidence, "capability": capability}
+            if isinstance(meta.get("args"), dict):
+                step["args"] = meta["args"]
+            if meta.get("saveReport") is True:
+                step["saveReport"] = True
+            route.append(step)
+    return route
+
+
+def parse_json_todo_goal_state(goal_id: str, data: dict) -> dict:
+    items = [item for item in data.get("items", []) if isinstance(item, dict)] if isinstance(data.get("items"), list) else []
+    raw_destination = data.get("destination") if isinstance(data.get("destination"), dict) else {}
+    route = data.get("route") if isinstance(data.get("route"), list) else route_from_items(items)
+    evidence = string_list(raw_destination.get("evidence")) or string_list(data.get("evidence"))
+    if not evidence:
+        evidence = [
+            str((item.get("meta") if isinstance(item.get("meta"), dict) else {}).get("evidence") or item.get("id"))
+            for item in items
+            if item.get("id")
+        ]
+    facts = data.get("facts") if isinstance(data.get("facts"), dict) else {}
+    facts = dict(facts)
+    for item in items:
+        meta = item.get("meta") if isinstance(item.get("meta"), dict) else {}
+        key = meta.get("evidence") or item.get("id")
+        if isinstance(key, str):
+            facts[key] = item.get("completed") is True
+    capabilities = string_list(data.get("capabilities"))
+    if not capabilities:
+        capabilities = [step["capability"] for step in route if isinstance(step.get("capability"), str)]
+    outcome = data.get("description") if isinstance(data.get("description"), str) else raw_destination.get("outcome")
+    parsed = dict(data)
+    parsed.update(
+        {
+            "id": goal_id,
+            "version": data.get("version", 1),
+            "state": data.get("state", "active"),
+            "type": data.get("type", "general"),
+            "destination": {**raw_destination, "outcome": outcome if isinstance(outcome, str) else "", "evidence": evidence},
+            "capabilities": capabilities,
+            "route": route,
+            "facts": facts,
+            "blockers": string_list(data.get("blockers")),
+        }
+    )
+    return parsed
+
+
+def parse_todo_goal_state(goal_id: str, text: str) -> dict:
+    data = parse_json_object(text)
+    if data is None:
+        raise ValueError(f"goal {goal_id} todo state must be JSON")
+    return parse_json_todo_goal_state(goal_id, data)
+
+
+def todo_items_from_state(data: dict, now: str) -> list[dict]:
+    destination = data.get("destination") if isinstance(data.get("destination"), dict) else {}
+    evidence = string_list(destination.get("evidence"))
+    route = data.get("route") if isinstance(data.get("route"), list) else []
+    facts = data.get("facts") if isinstance(data.get("facts"), dict) else {}
+    route_by_evidence = {
+        step.get("evidence"): step
+        for step in route
+        if isinstance(step, dict) and isinstance(step.get("evidence"), str)
+    }
+    if evidence:
+        items = []
+        for key in evidence:
+            step = route_by_evidence.get(key) if isinstance(route_by_evidence.get(key), dict) else {}
+            completed = facts.get(key) is True
+            items.append(
+                {
+                    "id": key,
+                    "title": step.get("stage") if isinstance(step.get("stage"), str) else key,
+                    "body": "",
+                    "assignee": None,
+                    "completed": completed,
+                    "createdAt": data.get("createdAt") if isinstance(data.get("createdAt"), str) else now,
+                    "completedAt": data.get("updatedAt") if completed and isinstance(data.get("updatedAt"), str) else None,
+                    "meta": {
+                        "evidence": key,
+                        **({"stage": step["stage"]} if isinstance(step.get("stage"), str) else {}),
+                        **({"capability": step["capability"]} if isinstance(step.get("capability"), str) else {}),
+                        **({"args": step["args"]} if isinstance(step.get("args"), dict) else {}),
+                        **({"saveReport": True} if step.get("saveReport") is True else {}),
+                    },
+                }
+            )
+        return items
+    return [
+        {
+            "id": capability,
+            "title": capability,
+            "body": "",
+            "assignee": None,
+            "completed": False,
+            "createdAt": data.get("createdAt") if isinstance(data.get("createdAt"), str) else now,
+            "completedAt": None,
+            "meta": {"capability": capability},
+        }
+        for capability in string_list(data.get("capabilities"))
+    ]
+
+
+def serialize_todo_goal_state(goal_id: str, data: dict, now: str) -> str:
+    destination = data.get("destination") if isinstance(data.get("destination"), dict) else {}
+    outcome = destination.get("outcome") if isinstance(destination.get("outcome"), str) else ""
+    record = dict(data)
+    record["version"] = 1
+    record["id"] = goal_id
+    record["title"] = goal_id
+    record["description"] = outcome
+    record["createdAt"] = data.get("createdAt") if isinstance(data.get("createdAt"), str) else now
+    record["managed"] = True
+    record["managedModel"] = "agentLoop" if record.get("scheduleMode") == "agentLoop" or record.get("type") == "agentLoop" else "agentGoal"
+    record["evidence"] = string_list(destination.get("evidence"))
+    record["items"] = todo_items_from_state(data, now)
+    return json.dumps(record, indent=2) + "\n"

package/dist/runtime-services/goal-scheduler/profile.json

@@ -0,0 +1,51 @@
+{
+  "internal": true,
+  "role": "watch",
+  "kind": "scheduled",
+  "schedule": "*/5 * * * *",
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [
+    {
+      "name": "python3",
+      "install": {
+        "required": true,
+        "checkCommand": "command -v python3"
+      },
+      "verify": "python3 --version",
+      "usage": "scheduler.sh parses each managed goal todo file",
+      "allowedUses": []
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "dispatchAgencyLoops"
+      },
+      {
+        "shell": "scheduler.sh",
+        "timeoutSec": 1800
+      },
+      {
+        "script": "skipAgent"
+      }
+    ],
+    "postflight": []
+  },
+  "inputs": [],
+  "name": "goal-scheduler"
+}