@kody-ade/kody-engine 0.4.232 → 0.4.234

package/dist/bin/kody.js

@@ -15,7 +15,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@kody-ade/kody-engine",
-      version: "0.4.232",
+      version: "0.4.234",
       description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
       license: "MIT",
       type: "module",
@@ -3121,6 +3121,7 @@ function loadProfile(profilePath) {
       action: typeof r.action === "string" && r.action.trim() ? r.action.trim() : void 0,
       executable: execRef,
       describe: typeof r.describe === "string" ? r.describe : base.describe,
+      capabilityKind: parseCapabilityKind(profilePath, r.capabilityKind) ?? base.capabilityKind,
       staff: typeof r.staff === "string" && r.staff.trim() ? r.staff.trim() : base.staff,
       every: typeof r.every === "string" && r.every.trim() ? r.every.trim() : void 0,
       dutyTools: parseStringArray(r.dutyTools ?? r.tools) ?? base.dutyTools,
@@ -3165,6 +3166,7 @@ function loadProfile(profilePath) {
     action: typeof r.action === "string" && r.action.trim() ? r.action.trim() : void 0,
     executable: void 0,
     describe: typeof r.describe === "string" ? r.describe : "",
+    capabilityKind: parseCapabilityKind(profilePath, r.capabilityKind),
     // Optional persona to run as. Empty/blank string → undefined (no persona).
     staff: typeof r.staff === "string" && r.staff.trim() ? r.staff.trim() : void 0,
     // Optional recurrence cadence (scheduled duty). Blank → undefined (on-demand).
@@ -3255,6 +3257,13 @@ function requireString(p, r, key) {
   }
   return v;
 }
+function parseCapabilityKind(p, raw) {
+  if (raw === void 0 || raw === null || raw === "") return void 0;
+  if (typeof raw !== "string" || !VALID_CAPABILITY_KINDS.has(raw)) {
+    throw new ProfileError(p, `"capabilityKind" must be one of: observe | act | verify`);
+  }
+  return raw;
+}
 function parseStringArray(raw) {
   if (!Array.isArray(raw)) return void 0;
   const values = raw.map((t) => String(t).trim()).filter(Boolean);
@@ -3331,6 +3340,17 @@ function parseCliTools(p, raw) {
   if (!Array.isArray(raw)) throw new ProfileError(p, `"cliTools" must be an array or absent`);
   const out = [];
   for (const [i, item] of raw.entries()) {
+    if (typeof item === "string" && item.trim()) {
+      const name = item.trim();
+      out.push({
+        name,
+        install: { required: false, checkCommand: `command -v ${name}` },
+        verify: `command -v ${name}`,
+        usage: "",
+        allowedUses: []
+      });
+      continue;
+    }
     if (!item || typeof item !== "object") {
       throw new ProfileError(p, `cliTools[${i}] must be an object`);
     }
@@ -3490,7 +3510,7 @@ function parseScriptList(p, key, raw) {
   }
   return out;
 }
-var VALID_INPUT_TYPES, VALID_PERMISSION_MODES, VALID_ROLES, VALID_CONTAINER_CHILD_TARGETS, VALID_PHASES, KNOWN_PROFILE_KEYS;
+var VALID_INPUT_TYPES, VALID_PERMISSION_MODES, VALID_ROLES, VALID_CONTAINER_CHILD_TARGETS, VALID_PHASES, VALID_CAPABILITY_KINDS, KNOWN_PROFILE_KEYS;
 var init_profile = __esm({
   "src/profile.ts"() {
     "use strict";
@@ -3506,6 +3526,7 @@ var init_profile = __esm({
     VALID_ROLES = /* @__PURE__ */ new Set(["primitive", "orchestrator", "container", "watch", "utility"]);
     VALID_CONTAINER_CHILD_TARGETS = /* @__PURE__ */ new Set(["issue", "pr"]);
     VALID_PHASES = /* @__PURE__ */ new Set(["research", "planning", "implementing", "reviewing", "shipped", "failed", "idle"]);
+    VALID_CAPABILITY_KINDS = /* @__PURE__ */ new Set(["observe", "act", "verify"]);
     KNOWN_PROFILE_KEYS = /* @__PURE__ */ new Set([
       "name",
       "action",
@@ -3515,6 +3536,7 @@ var init_profile = __esm({
       "dutyTools",
       "tools",
       "mentions",
+      "capabilityKind",
       "stage",
       "readsFrom",
       "writesTo",
@@ -5723,6 +5745,132 @@ var init_state2 = __esm({
   }
 });
 
+// src/goal/typeDefinitions.ts
+function cloneRoute(route) {
+  return route.map((step) => ({
+    stage: step.stage,
+    evidence: step.evidence,
+    duty: step.duty,
+    ...step.executable ? { executable: step.executable } : {},
+    ...step.args ? { args: structuredClone(step.args) } : {}
+  }));
+}
+function stringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : null;
+}
+function routeArray(value) {
+  if (!Array.isArray(value)) return null;
+  const route = [];
+  for (const item of value) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+    const raw = item;
+    if (typeof raw.stage !== "string" || typeof raw.evidence !== "string" || typeof raw.duty !== "string") return null;
+    route.push({
+      stage: raw.stage,
+      evidence: raw.evidence,
+      duty: raw.duty,
+      executable: typeof raw.executable === "string" ? raw.executable : void 0,
+      args: raw.args && typeof raw.args === "object" && !Array.isArray(raw.args) ? { ...raw.args } : void 0
+    });
+  }
+  return route;
+}
+function managedGoalTypeDefinition(type) {
+  return Object.prototype.hasOwnProperty.call(GOAL_TYPE_DEFINITIONS, type) ? GOAL_TYPE_DEFINITIONS[type] : null;
+}
+function expandManagedGoalState(state) {
+  const type = typeof state.extra.type === "string" ? state.extra.type : "";
+  const definition = managedGoalTypeDefinition(type);
+  if (!definition) return state;
+  const destination = state.extra.destination && typeof state.extra.destination === "object" && !Array.isArray(state.extra.destination) ? { ...state.extra.destination } : {};
+  const outcome = typeof destination.outcome === "string" ? destination.outcome : "";
+  const evidence = stringArray(destination.evidence);
+  const duties = stringArray(state.extra.duties);
+  const route = routeArray(state.extra.route);
+  const facts = state.extra.facts && typeof state.extra.facts === "object" && !Array.isArray(state.extra.facts) ? { ...state.extra.facts } : {};
+  const blockers = stringArray(state.extra.blockers);
+  return {
+    ...state,
+    extra: {
+      ...state.extra,
+      type: definition.type,
+      destination: {
+        ...destination,
+        outcome,
+        evidence: evidence && evidence.length > 0 ? evidence : [...definition.evidence]
+      },
+      duties: duties && duties.length > 0 ? duties : [...definition.duties],
+      route: route && route.length > 0 ? route : cloneRoute(definition.route),
+      facts,
+      blockers: blockers ?? []
+    }
+  };
+}
+var GOAL_TYPE_DEFINITIONS;
+var init_typeDefinitions = __esm({
+  "src/goal/typeDefinitions.ts"() {
+    "use strict";
+    GOAL_TYPE_DEFINITIONS = {
+      improve: {
+        type: "improve",
+        evidence: ["planReady", "changeImplemented", "changeVerified"],
+        duties: ["plan", "fix", "review"],
+        route: [
+          { stage: "plan", evidence: "planReady", duty: "plan", executable: "plan" },
+          { stage: "implement", evidence: "changeImplemented", duty: "fix", executable: "fix" },
+          { stage: "review", evidence: "changeVerified", duty: "review", executable: "review" }
+        ]
+      },
+      maintain: {
+        type: "maintain",
+        evidence: [],
+        duties: ["cleanup", "code-health", "docs-health", "documentation-maintenance", "memory-compaction", "repo-graph", "skills-research"],
+        route: []
+      },
+      monitor: {
+        type: "monitor",
+        evidence: [],
+        duties: ["health-check", "pr-health-triage", "qa-sweep"],
+        route: []
+      },
+      release: {
+        type: "release",
+        evidence: ["releasePrExists", "mainMerged", "productionDeployed"],
+        duties: ["release", "release-merge", "vercel-production-deploy"],
+        route: [
+          {
+            stage: "release",
+            evidence: "releasePrExists",
+            duty: "release",
+            executable: "release-prepare",
+            args: { issue: { fact: "issue" }, goal: { fact: "goalId" } }
+          },
+          {
+            stage: "merge",
+            evidence: "mainMerged",
+            duty: "release-merge",
+            executable: "release-merge",
+            args: { pr: { fact: "releasePr" }, issue: { fact: "issue" }, goal: { fact: "goalId" } }
+          },
+          {
+            stage: "publish",
+            evidence: "productionDeployed",
+            duty: "vercel-production-deploy",
+            executable: "vercel-production-deploy",
+            args: { goal: { fact: "goalId" } }
+          }
+        ]
+      },
+      checklist: {
+        type: "checklist",
+        evidence: ["checklistComplete"],
+        duties: ["task-verifier"],
+        route: [{ stage: "verify", evidence: "checklistComplete", duty: "task-verifier", executable: "task-verifier" }]
+      }
+    };
+  }
+});
+
 // src/stateBranch.ts
 function is404(err) {
   const msg = err instanceof Error ? err.message : String(err);
@@ -6335,12 +6483,64 @@ function readSimpleGoalTaskSummary(goalId, cwd) {
   const open = issues.filter((issue) => String(issue.state ?? "").toLowerCase() === "open").length;
   return { total, open };
 }
+function ensureIssueFactIfNeeded(goal, goalId, cwd) {
+  if (!routeNeedsIssueFact(goal)) return;
+  const existing = normalizeIssueNumber(goal.facts.issue);
+  if (existing !== null) {
+    goal.facts.issue = existing;
+    return;
+  }
+  goal.facts.issue = findExistingGoalIssue(goalId, cwd) ?? createGoalIssue(goal, goalId, cwd);
+}
+function routeNeedsIssueFact(goal) {
+  return goal.route.some(
+    (step) => Object.values(step.args ?? {}).some((value) => {
+      if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+      const record = value;
+      return Object.keys(record).length === 1 && record.fact === "issue";
+    })
+  );
+}
+function normalizeIssueNumber(value) {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+  if (typeof value === "string" && /^\d+$/.test(value)) return Number(value);
+  return null;
+}
+function goalIssueMarker(goalId) {
+  return `<!-- kody-managed-goal: ${goalId} -->`;
+}
+function findExistingGoalIssue(goalId, cwd) {
+  const marker = goalIssueMarker(goalId);
+  const raw = gh(["issue", "list", "--state", "all", "--limit", "100", "--json", "number,body"], { cwd });
+  const issues = JSON.parse(raw);
+  const match = issues.find((issue) => typeof issue.number === "number" && issue.body?.includes(marker));
+  return match?.number ?? null;
+}
+function createGoalIssue(goal, goalId, cwd) {
+  const prefix = goal.type === "release" ? "Release" : "Goal";
+  const outcome = goal.destination.outcome.trim() || goalId;
+  const title = `${prefix}: ${outcome}`.slice(0, 120);
+  const body = [
+    `Managed goal: \`${goalId}\``,
+    "",
+    `Finish line: ${outcome}`,
+    "",
+    "This issue was created by Kody so goal duties that require an issue can run end to end.",
+    "",
+    goalIssueMarker(goalId)
+  ].join("\n");
+  const out = gh(["issue", "create", "--title", title, "--body-file", "-"], { input: body, cwd });
+  const match = out.match(/\/issues\/(\d+)(?:[/?#]|$)/);
+  if (!match) throw new Error(`gh issue create returned unexpected output: ${out}`);
+  return Number(match[1]);
+}
 var advanceManagedGoal;
 var init_advanceManagedGoal = __esm({
   "src/scripts/advanceManagedGoal.ts"() {
     "use strict";
     init_manager();
     init_state2();
+    init_typeDefinitions();
     init_issue();
     init_goalDutyScheduling();
     advanceManagedGoal = async (ctx) => {
@@ -6352,6 +6552,7 @@ var init_advanceManagedGoal = __esm({
         return;
       }
       ctx.data.goalOriginalStateText = serializeGoalState(goal.raw);
+      goal.raw = expandManagedGoalState(goal.raw);
       const managed = managedGoalFromState(goal.raw);
       if (!managed) {
         ctx.output.reason = "goal has no managed-goal contract; nothing to advance";
@@ -6363,6 +6564,17 @@ var init_advanceManagedGoal = __esm({
         if (previousGoalIdFact === void 0) delete managed.facts.goalId;
         else managed.facts.goalId = previousGoalIdFact;
       };
+      try {
+        ensureIssueFactIfNeeded(managed, goal.id, ctx.cwd);
+      } catch (err) {
+        const reason = `failed to prepare goal issue fact: ${err instanceof Error ? err.message : String(err)}`;
+        managed.stage = "blocked";
+        if (!managed.blockers.includes(reason)) managed.blockers.push(reason);
+        restoreGoalIdFact();
+        goal.raw = writeManagedGoalToState({ ...goal.raw, state: goal.state }, managed);
+        ctx.output.reason = reason;
+        return;
+      }
       if (isDutyCadenceGoal(managed, goal.raw.extra)) {
         const previousScheduleState = goal.raw.extra.scheduleState && typeof goal.raw.extra.scheduleState === "object" ? goal.raw.extra.scheduleState : void 0;
         const decision2 = await planGoalDutySchedule({
@@ -16554,15 +16766,23 @@ async function runCi(argv) {
   const dispatchEventPath = process.env.GITHUB_EVENT_PATH;
   let manualWorkflowDispatch = false;
   let forceRunAction = null;
+  let forceRunCliArgs = {};
   if (!args.issueNumber && !autoFallback && eventName === "workflow_dispatch" && dispatchEventPath && fs42.existsSync(dispatchEventPath)) {
     try {
       const evt = JSON.parse(fs42.readFileSync(dispatchEventPath, "utf-8"));
       const issueInput = parseInt(String(evt?.inputs?.issue_number ?? ""), 10);
       const sessionInput = String(evt?.inputs?.sessionId ?? "");
       const dutyInput = String(evt?.inputs?.duty ?? evt?.inputs?.executable ?? "").trim();
+      const messageInput = String(evt?.inputs?.message ?? "").trim();
       const noTarget = !sessionInput && !(Number.isFinite(issueInput) && issueInput > 0);
-      if (noTarget && dutyInput) forceRunAction = dutyInput;
-      else manualWorkflowDispatch = noTarget;
+      if (noTarget && dutyInput) {
+        forceRunAction = dutyInput;
+        if (dutyInput === "goal-manager" && messageInput) {
+          forceRunCliArgs = { goal: messageInput };
+        }
+      } else {
+        manualWorkflowDispatch = noTarget;
+      }
     } catch {
       manualWorkflowDispatch = false;
     }
@@ -16575,6 +16795,10 @@ async function runCi(argv) {
 `);
       return 64;
     }
+    if (route.executable === "goal-manager" && typeof forceRunCliArgs.goal !== "string") {
+      process.stderr.write("[kody] manual goal-manager run requires message goal id\n");
+      return 64;
+    }
     process.stdout.write(`\u2192 kody: manual one-shot run of duty action ${route.action} (${route.duty})
 
 `);
@@ -16611,7 +16835,7 @@ async function runCi(argv) {
         action: route.action,
         duty: route.duty,
         executable: route.executable,
-        cliArgs: route.cliArgs,
+        cliArgs: { ...route.cliArgs, ...forceRunCliArgs },
         flavor: "instant",
         force: true
       },

package/dist/executables/types.ts

@@ -15,6 +15,8 @@ import type { Phase } from "../state.js"
 // Profile shape (mirrors the JSON on disk).
 // ────────────────────────────────────────────────────────────────────────────
 
+export type CapabilityKind = "observe" | "act" | "verify"
+
 export interface Profile {
   name: string
   /**
@@ -33,6 +35,11 @@ export interface Profile {
    */
   staff?: string
   describe: string
+  /**
+   * Author-facing capability promise for a duty/executable. 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.
    *   - primitive:    single-step agent executor (flow → agent → verify → commit → PR).
@@ -390,6 +397,58 @@ export interface OutputContract {
   }
 }
 
+export interface CapabilityAlert {
+  level?: "info" | "warning" | "error"
+  message: string
+}
+
+export interface CapabilitySuggestedAction {
+  action: string
+  args?: Record<string, unknown>
+  reason?: string
+}
+
+export interface CapabilityResourceRef {
+  type: string
+  id?: string | number
+  number?: number
+  url?: string
+  name?: string
+}
+
+export interface CapabilityEvidenceItem {
+  source?: string
+  message: string
+  url?: string
+}
+
+export interface ObserveResult {
+  kind: "observe"
+  facts?: Record<string, unknown>
+  alerts?: CapabilityAlert[]
+  suggestedActions?: CapabilitySuggestedAction[]
+  evidence?: Record<string, unknown>
+}
+
+export interface ActResult {
+  kind: "act"
+  status: "created" | "changed" | "triggered" | "skipped" | "failed"
+  changedResources?: CapabilityResourceRef[]
+  createdResources?: CapabilityResourceRef[]
+  actionResult?: Record<string, unknown>
+  evidence?: Record<string, unknown>
+}
+
+export interface VerifyResult {
+  kind: "verify"
+  passed: boolean
+  evidence?: CapabilityEvidenceItem[]
+  blockers?: string[]
+  facts?: Record<string, unknown>
+}
+
+export type CapabilityResult = ObserveResult | ActResult | VerifyResult
+
 // ────────────────────────────────────────────────────────────────────────────
 // Run-time context passed to every script.
 // ────────────────────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.232",
+  "version": "0.4.234",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",