@ikenga/contract 0.6.0 → 0.9.0

package/src/host-verbs.ts

@@ -0,0 +1,207 @@
+/**
+ * Host-bridge verb shapes for the agent-ops pkg — the **G-TRIGGER** freeze gate.
+ *
+ * Unlike the kernel RPC methods in `rpc.ts`, `host.*` verbs are dispatched
+ * FE-side in the iframe host (`shell/src/components/pkg/pkg-iframe-host.tsx`)
+ * and invoked from the iframe via `app.callServerTool({ name, arguments })`,
+ * returning their payload on `res.structuredContent`. These types are the
+ * shared contract the shell (WP-09) produces and the agent-ops pkg
+ * (WP-08 reads, WP-12 writes) consumes. Frozen so changing them after both
+ * sides exist forces a cross-repo re-sync.
+ *
+ * Gated by `capabilities.agentOps` (see `AgentOpsCapabilitySchema`).
+ */
+
+/** Typed failure codes a host.agentOps verb returns on the `{ ok: false }`
+ *  branch, so the pkg UI can render a specific state rather than a raw string.
+ *  - `daemon_down`   — `~/.agent-ops/daemon.lock` missing or daemon not alive
+ *  - `unauthorized`  — the daemon rejected the token (401) — should not happen
+ *                      in normal operation (the shell reads the live lock)
+ *  - `not_found`     — no job with that id (daemon 404 / config miss)
+ *  - `disabled`      — job is disabled, cannot run-now (daemon 409)
+ *  - `forbidden`     — daemon rejected host/origin/method (403/405)
+ *  - `io_error`      — lock/config file unreadable or unwritable
+ *  - `error`         — any other failure */
+export type AgentOpsErrorCode =
+  | 'daemon_down'
+  | 'unauthorized'
+  | 'not_found'
+  | 'disabled'
+  | 'forbidden'
+  | 'io_error'
+  | 'error';
+
+export interface AgentOpsErrorResult {
+  ok: false;
+  code: AgentOpsErrorCode;
+  /** HTTP status from the daemon when applicable, else null. */
+  status: number | null;
+  error: string;
+}
+
+/** `host.agentOps.runNow({ jobId })` — fire an out-of-schedule run via the
+ *  daemon's localhost trigger endpoint. The shell reads the 0600
+ *  `~/.agent-ops/daemon.lock` for `{ port, secret }` and POSTs
+ *  `127.0.0.1:<port>/jobs/<jobId>/trigger` with BOTH required headers
+ *  (`x-agent-ops-token: <secret>` + `x-agent-ops-trigger: 1`). */
+export interface AgentOpsRunNowArgs {
+  jobId: string;
+}
+export type AgentOpsRunNowResult =
+  | { ok: true; status: number; message: string }
+  | AgentOpsErrorResult;
+
+/** `host.agentOps.setEnabled({ jobId, enabled })` — flip a job's `enabled`
+ *  flag in the project-scoped config (`~/.atelier/skill-agent-ops/jobs.json`).
+ *  The daemon honors it on next config load. Does NOT touch the executor. */
+export interface AgentOpsSetEnabledArgs {
+  jobId: string;
+  enabled: boolean;
+}
+export type AgentOpsSetEnabledResult =
+  | { ok: true; jobId: string; enabled: boolean }
+  | AgentOpsErrorResult;
+
+/** The editable job fields the CRUD form sends to `host.agentOps.upsertJob`.
+ *  The host fills JobDefinition defaults (schedule_dialect, timeout_ms, retries,
+ *  backoff, concurrency_policy) for any omitted field; the daemon's Zod loader
+ *  is the final validation backstop on next config load. */
+export interface AgentOpsJobInput {
+  id: string;
+  label: string;
+  schedule: string;
+  timezone?: string;
+  enabled?: boolean;
+  mode?: 'agent' | 'script';
+  command: string;
+  model?: string | null;
+  agent?: string | null;
+  schedule_dialect?: '5f' | '6f';
+  timeout_ms?: number;
+}
+
+/** `host.agentOps.upsertJob({ job })` — create-or-update a job in the
+ *  project-scoped config (atomic rewrite; replace by id if present, else
+ *  append). The daemon honors it on next config load. Validating-only write —
+ *  the shell does NOT run the job, never becomes the executor. */
+export interface AgentOpsUpsertJobArgs {
+  job: AgentOpsJobInput;
+}
+export type AgentOpsUpsertJobResult =
+  | { ok: true; jobId: string; created: boolean }
+  | AgentOpsErrorResult;
+
+/** `host.agentOps.deleteJob({ jobId })` — remove a job from the project-scoped
+ *  config (atomic rewrite). The daemon stops scheduling it on next load. */
+export interface AgentOpsDeleteJobArgs {
+  jobId: string;
+}
+export type AgentOpsDeleteJobResult =
+  | { ok: true; jobId: string }
+  | AgentOpsErrorResult;
+
+/** `host.agentOps.tailRun({ jobId, offset? })` — read the live (or last-completed)
+ *  run output for a job by byte-range, for the pkg's Live-output view.
+ *
+ *  Unlike the other agent-ops verbs (which reach the daemon's localhost endpoint
+ *  or rewrite its config), tailRun is a pure **filesystem read on the shell's own
+ *  event loop**: it opens the per-job marker (`~/.agent-ops/runs/<slug>.marker.json`)
+ *  to learn the current run's `tailPath` + `status` + `pid`, then reads that tail
+ *  file from `offset` forward (capped per call). Because it never touches the
+ *  daemon, the daemon being blocked mid-run (synchronously executing a job) is
+ *  irrelevant — the shell still streams whatever the child has teed to disk so far.
+ *
+ *  Mechanism is **script-mode only**: the daemon tees a script job's combined
+ *  stdout/stderr to the tail file as it runs. Agent jobs (`claude -p`) stay
+ *  byte-for-byte unchanged and have no tail file, so tailRun returns an empty
+ *  chunk with `mode:'agent'` (the pkg renders 'live output not available for
+ *  agent jobs' + a spinner driven off the marker's `status`).
+ *
+ *  Polling loop: call with `offset:0` first, then feed the returned `nextOffset`
+ *  back on each poll. `eof` true means the reader caught up to the current end of
+ *  file; keep polling while `running` is true. After a run completes the marker
+ *  still points at the final tail, so `running:false` STILL returns the final
+ *  chunk for scrollback — the view shows the completed output, not an empty pane.
+ *
+ *  - `running`     — `status === 'running'` AND the marker's `pid` is alive.
+ *  - `status`      — the marker's `status` (`'running' | 'done'`), or `null` when
+ *                    no marker exists yet (job has never produced a run).
+ *  - `startedAtMs` — the run's start epoch-ms from the marker, else `null`.
+ *  - `mode`        — `'script'` (has a tail) / `'agent'` (no tail) / `null` (no marker).
+ *  - `chunk`       — lossy-utf8 decode of the bytes read this call (may be empty).
+ *  - `nextOffset`  — `offset + bytesRead`; pass back on the next poll.
+ *  - `eof`         — reached the current end of the tail file.
+ *
+ *  Best-effort + non-throwing on the shell side: a missing marker / missing tail /
+ *  unreadable file resolves to `{ ok:true, chunk:'', eof:true, ... }` rather than
+ *  an error, so the view degrades to 'no output yet'. Only a path-escape attempt
+ *  (marker.tailPath pointing outside `~/.agent-ops/runs/`) maps to an
+ *  `{ ok:false, code:'io_error' }`. */
+export interface AgentOpsTailRunArgs {
+  jobId: string;
+  /** Byte offset into the tail file to read from. Defaults to 0. */
+  offset?: number;
+}
+export type AgentOpsTailRunResult =
+  | {
+      ok: true;
+      running: boolean;
+      status: 'running' | 'done' | null;
+      startedAtMs: number | null;
+      mode: 'agent' | 'script' | null;
+      chunk: string;
+      nextOffset: number;
+      eof: boolean;
+    }
+  | AgentOpsErrorResult;
+
+/** A merged config+state row as returned by `host.agentOps.listJobs`. Config
+ *  fields come from `~/.atelier/skill-agent-ops/jobs.json` (a JobDefinition);
+ *  `state` is that job's entry in `.company/cron/jobs-state.json` (or null if
+ *  it has never run). Field casing matches the on-disk files (camelCase state);
+ *  the pkg's data layer (WP-08) maps this into the snake_case G-VIEW. */
+export interface AgentOpsRawJobState {
+  nextRunAtMs: number | null;
+  lastRunAtMs: number | null;
+  lastStatus: string | null;
+  consecutiveErrors: number;
+  lastDurationMs: number | null;
+  totalCostUsd: number | null;
+  totalRuns: number | null;
+  lastUsage: {
+    costUsd: number | null;
+    numTurns: number | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    sessionId: string | null;
+  } | null;
+}
+export interface AgentOpsRawJob {
+  id: string;
+  label: string;
+  schedule: string;
+  schedule_dialect: '5f' | '6f';
+  timezone: string;
+  enabled: boolean;
+  command: string;
+  mode: 'agent' | 'script';
+  model: string | null;
+  agent: string | null;
+  _disabledReason: string | null;
+  state: AgentOpsRawJobState | null;
+}
+
+/** `host.agentOps.listJobs({})` — read the project-scoped job config + the
+ *  daemon's runtime state file and return both, merged per job, plus daemon
+ *  liveness. Run history (cron_job_runs / agent_runs) is NOT included here —
+ *  the pkg reads that directly via `host.dbQuery`. */
+export type AgentOpsListJobsArgs = Record<string, never>;
+export type AgentOpsListJobsResult =
+  | {
+      ok: true;
+      daemon_up: boolean;
+      daemon_pid: number | null;
+      jobs: AgentOpsRawJob[];
+    }
+  | AgentOpsErrorResult;

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './manifest.js';
 export * from './rpc.js';
+export * from './host-verbs.js';
 export * from './engine/index.js';
 export * from './scopes.js';
 export * from './iyke.js';

package/src/manifest.test.ts

@@ -0,0 +1,97 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  ManifestSchema,
+  RequiresEntrySchema,
+  RequireSourceSchema,
+} from './manifest.js';
+
+// ─── WP-11 — `requires` field (ADR-015 §3) ──────────────────────────────────
+
+const BASE = {
+  id: 'com.ikenga.studio',
+  name: 'Studio',
+  version: '0.1.0',
+  ikenga_api: '1',
+};
+
+test('RequiresEntry: full shape parses', () => {
+  const e = RequiresEntrySchema.parse({
+    kind: 'skill',
+    name: '@ikenga/studio-beat-detect',
+    source: 'npx',
+    ref: 'v1.2.0',
+  });
+  assert.equal(e.kind, 'skill');
+  assert.equal(e.source, 'npx');
+  assert.equal(e.ref, 'v1.2.0');
+});
+
+test('RequiresEntry: source + ref optional', () => {
+  const e = RequiresEntrySchema.parse({ kind: 'skill', name: 'skill-core' });
+  assert.equal(e.source, undefined);
+  assert.equal(e.ref, undefined);
+});
+
+test('RequiresEntry: rejects unknown field (.strict mirrors Rust deny_unknown_fields)', () => {
+  assert.throws(() =>
+    RequiresEntrySchema.parse({ kind: 'skill', name: 'skill-core', bogus: true }),
+  );
+});
+
+test('RequiresEntry: kind bundle is accepted (WP-18 G-BUNDLE)', () => {
+  // WP-18 locked design decision 4: `RequiresEntrySchema.kind` is `z.string()`
+  // (a free string, not a closed enum), so a `requires` entry may reference a
+  // bundle — `{kind:"bundle", name}` parses and carries the kind through. This
+  // is the contract-side half of the G-BUNDLE "requires kind:bundle parses" DoD.
+  const e = RequiresEntrySchema.parse({ kind: 'bundle', name: 'studio-archetypes' });
+  assert.equal(e.kind, 'bundle');
+  assert.equal(e.name, 'studio-archetypes');
+});
+
+test('RequiresEntry: rejects an out-of-set source', () => {
+  assert.throws(() =>
+    RequiresEntrySchema.parse({ kind: 'skill', name: 'x', source: 'ftp' }),
+  );
+});
+
+test('RequireSource: only git|npx|catalog|local', () => {
+  for (const s of ['git', 'npx', 'catalog', 'local']) {
+    assert.equal(RequireSourceSchema.parse(s), s);
+  }
+  assert.throws(() => RequireSourceSchema.parse('http'));
+});
+
+test('Manifest: requires parses and round-trips', () => {
+  const m = ManifestSchema.parse({
+    ...BASE,
+    requires: [
+      { kind: 'skill', name: '@ikenga/studio-archetypes', source: 'npx' },
+      { kind: 'skill', name: 'skill-core', source: 'git', ref: 'v1.0.0' },
+      { kind: 'skill', name: '@ikenga/studio-doctor' },
+    ],
+  });
+  assert.equal(m.requires.length, 3);
+  assert.equal(m.requires[0].name, '@ikenga/studio-archetypes');
+  assert.equal(m.requires[2].source, undefined);
+});
+
+test('Manifest: requires defaults to [] when absent (pre-Phase-4 manifest)', () => {
+  const m = ManifestSchema.parse({ ...BASE });
+  assert.deepEqual(m.requires, []);
+});
+
+test('Manifest: retired bundling fields are no longer part of the type (WP-17)', () => {
+  // ADR-015 decision 4: `skills`/`commands`/`agents` were hard-retired from the
+  // schema (lockstep with the Rust `deny_unknown_fields` Manifest, which REJECTS
+  // them — the authoritative loader). ManifestSchema is non-strict, so a stray
+  // legacy key is stripped rather than rejected here; assert it does not survive
+  // onto the parsed object.
+  const m = ManifestSchema.parse({ ...BASE, skills: 'skills', commands: 'commands' }) as Record<
+    string,
+    unknown
+  >;
+  assert.equal(m.skills, undefined);
+  assert.equal(m.commands, undefined);
+});

package/src/manifest.ts

@@ -11,7 +11,9 @@
 import { z } from 'zod';
 import { EngineProvidesSchema } from './engine/index.js';
 
-export const IKENGA_API_VERSION = 1 as const;
+// v2 (WP-05): added capabilities.sqlite + permissions["sqlite.tables"];
+// permissions["supabase.tables"] kept as a compat alias for api=1 manifests.
+export const IKENGA_API_VERSION = 2 as const;
 export const IKENGA_API_MIN_SUPPORTED = 1 as const;
 
 // ---------- Sub-schemas ----------
@@ -60,6 +62,12 @@ export const PermissionsSchema = z.object({
   'fs.read': z.array(z.string()).default([]),
   'fs.write': z.array(z.string()).default([]),
   net: z.array(z.string()).default([]),
+  /** Local SQLite table patterns; validated against tables.json at install time.
+   *  For api ≥ 2 manifests. Replaces `supabase.tables`. */
+  'sqlite.tables': z.array(z.string()).default([]),
+  /** @deprecated api=1 compat alias for `sqlite.tables`. New manifests should
+   *  use `sqlite.tables` instead. Kept so ikenga_api="1" manifests parse
+   *  without errors during the transition window. */
   'supabase.tables': z.array(z.string()).default([]),
   'vault.keys': z.array(z.string()).default([]),
 }).default({});
@@ -135,6 +143,46 @@ export const CronEntrySchema = z.object({
   env_from_settings: z.array(z.string()).default([]),
 });
 
+/** Local SQLite capability (api ≥ 2). Threads the logical db name into the
+ *  iframe host context so the pkg can call `db_query` without hard-coding it.
+ *  Mirrors `SqliteCapability` in `shell/src-tauri/src/pkg/manifest.rs`. */
+export const SqliteCapabilitySchema = z.object({
+  /** Logical DB name. Currently only `"ikenga.local"` is supported.
+   *  Defaults to `"ikenga.local"` when omitted. */
+  db: z.string().default('ikenga.local'),
+});
+export type SqliteCapability = z.infer<typeof SqliteCapabilitySchema>;
+
+/** Supabase capability. Mirrors `SupabaseCapability` in
+ *  `shell/src-tauri/src/pkg/manifest.rs`. */
+export const SupabaseCapabilitySchema = z.object({
+  /** When true, mint fails if the Supabase vault keys are missing; when
+   *  false/omitted, missing keys surface as `supabase: null` in host context. */
+  required: z.boolean().default(false),
+});
+export type SupabaseCapability = z.infer<typeof SupabaseCapabilitySchema>;
+
+/** Native child-webview capability. Mirrors `WebviewCapability` in
+ *  `shell/src-tauri/src/pkg/manifest.rs`. */
+export const WebviewCapabilitySchema = z.object({
+  /** Whether this pkg may create child webviews via the kernel. Required for
+   *  any `ui.routes[]` entry with `kind = "webview"` to mount. */
+  child_webviews: z.boolean().default(false),
+  /** Named cookie/data partitions; empty = the implicit "default" partition. */
+  partitions: z.array(z.string()).default([]),
+});
+export type WebviewCapability = z.infer<typeof WebviewCapabilitySchema>;
+
+/** Agent-ops host-bridge capability (api ≥ 2). Opt-in to the privileged
+ *  `host.agentOps.*` verbs (run-now / enable-disable / list-jobs) the shell
+ *  exposes for the agent-ops observability pkg — these reach the always-on
+ *  cron daemon's localhost trigger endpoint and read the daemon's config +
+ *  state files, hops an iframe cannot make itself. Presence of the block is
+ *  the gate (mirrors the `capabilities.sqlite` opt-in). Mirrors
+ *  `AgentOpsCapability` in `shell/src-tauri/src/pkg/manifest.rs`. */
+export const AgentOpsCapabilitySchema = z.object({});
+export type AgentOpsCapability = z.infer<typeof AgentOpsCapabilitySchema>;
+
 export const WindowBlockSchema = z.object({
   label: z.string(),
   url: z.string(),
@@ -159,6 +207,39 @@ export const ScreenshotSchema = z.object({
 });
 export type Screenshot = z.infer<typeof ScreenshotSchema>;
 
+/** Forward-dependency source for a `requires[]` entry. Mirrors the Rust
+ *  `RequireSource` enum (`pkg/manifest.rs`) and the registry `ProvenanceSource`
+ *  set. Optional on an entry — absent means the resolver looks the dep up in the
+ *  store registry / catalog. */
+export const RequireSourceSchema = z.enum(['git', 'npx', 'catalog', 'local']);
+export type RequireSource = z.infer<typeof RequireSourceSchema>;
+
+/**
+ * One forward-dependency edge (`requires[]` element, ADR-015 §3 / Ọba WP-11).
+ * Names a standalone Ọba primitive a pkg `requires`; the resolver (WP-13/14)
+ * installs the closure at install/enable. This is a SEPARATE graph from a
+ * skill's `SKILL.md` `depends_on` (the G-04 authoring star, `skill-core`-only):
+ * a pkg `requires` MAY reference any primitive, and the publish-time lift
+ * (WP-12) compiles `depends_on` into this field. `.strict()` mirrors the Rust
+ * `deny_unknown_fields` on `RequiresEntry`. Source of truth: the Rust struct in
+ * `shell/src-tauri/src/pkg/manifest.rs` — keep in lockstep.
+ */
+export const RequiresEntrySchema = z
+  .object({
+    /** Primitive kind: skill | agent | command | hook | mcp. Kept a string so a
+     *  future kind doesn't break old manifests. */
+    kind: z.string(),
+    /** Primitive name (e.g. `skill-core`, `@ikenga/studio-beat-detect`). */
+    name: z.string(),
+    /** Optional fetch source. */
+    source: RequireSourceSchema.optional(),
+    /** Optional git tag/branch or version pin. The shape leaves room for an
+     *  explicit semver range later without another schema break. */
+    ref: z.string().optional(),
+  })
+  .strict();
+export type RequiresEntry = z.infer<typeof RequiresEntrySchema>;
+
 // ---------- Manifest ----------
 
 export const ManifestSchema = z.object({
@@ -176,9 +257,13 @@ export const ManifestSchema = z.object({
   targets: z.array(z.string()).default([]),
 
   // Capability blocks (all optional — kernel walks present blocks)
-  skills: z.string().optional(),
-  commands: z.string().optional(),
-  agents: z.string().optional(),
+  // NOTE (WP-17, ADR-015 decision 4): the `skills`/`commands`/`agents`
+  // asset-bundling fields were HARD-RETIRED (lockstep with the Rust
+  // `Manifest`). A pkg no longer embeds Claude-config assets; it only
+  // `requires` standalone Ọba primitives. The schema is `.strict()`, so a
+  // manifest still declaring any of them now FAILS validation (no deprecation
+  // window). The shell builtin `com.ikenga.iyke` places its skill/commands by
+  // convention from on-disk folders, not via a manifest field.
   mcp: z.array(McpServerSchema).default([]),
   sidecars: z.array(SidecarSpecSchema).default([]),
   permissions: PermissionsSchema,
@@ -190,6 +275,16 @@ export const ManifestSchema = z.object({
   window: WindowBlockSchema.optional(),
   queries: QueriesBlockSchema.optional(),
 
+  /** Optional capabilities the host resolves and injects at iframe-mount
+   *  time via the AppBridge `hostContext` handshake. Mirrors the Rust
+   *  `CapabilitiesBlock` in `shell/src-tauri/src/pkg/manifest.rs`. */
+  capabilities: z.object({
+    supabase: SupabaseCapabilitySchema.optional(),
+    sqlite: SqliteCapabilitySchema.optional(),
+    webview: WebviewCapabilitySchema.optional(),
+    agentOps: AgentOpsCapabilitySchema.optional(),
+  }).optional(),
+
   /**
    * Engine-adapter manifest block. Present iff this pkg is an engine-*
    * adapter. Declares the agent id, display name, capability snapshot,
@@ -205,6 +300,16 @@ export const ManifestSchema = z.object({
    * UI (engines, MCP-only servers) typically leave this empty.
    */
   screenshots: z.array(ScreenshotSchema).default([]),
+
+  /**
+   * Forward dependency declarations (ADR-015 §3 / Ọba WP-11). Each entry names a
+   * standalone primitive this pkg `requires`; the Ọba resolver installs the
+   * closure at install/enable. A SEPARATE graph from a skill's `depends_on` (the
+   * G-04 authoring star). Empty by default so pre-Phase-4 manifests are
+   * unaffected. Mirrors `requires: Vec<RequiresEntry>` on the Rust `Manifest`
+   * (`pkg/manifest.rs`) — keep in lockstep (`deny_unknown_fields`).
+   */
+  requires: z.array(RequiresEntrySchema).default([]),
 });
 
 export type Manifest = z.infer<typeof ManifestSchema>;

package/src/registry.ts

@@ -105,6 +105,15 @@ export const RegistryEntrySchema = z.object({
    * Lets the shell render a thumb without fetching the per-pkg detail file.
    */
   screenshot: z.string().url().optional(),
+  /**
+   * Catalog visibility. `"hidden"` keeps the pkg installable by exact name
+   * (CLI `add`/`update`, registry install, update detection) but omits it
+   * from the default browse/catalog surfaces — used for dev/test fixtures
+   * and scaffolds (e.g. `pkg-hello`, `pkg-engine-noop`, the cursor-agent
+   * scaffold). Absent ⇒ treated as `"public"`. Set by the publish pipeline's
+   * curation step (`ikenga-pkgs/scripts/update-registry-index.mjs`).
+   */
+  visibility: z.enum(['public', 'hidden']).optional(),
 });
 export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
 

package/src/scopes.ts

@@ -41,7 +41,7 @@ export const SCOPE_CATALOGUE: ScopeDef[] = [
   { scope: 'fs:write', description: 'Write files inside the shell-managed sandbox.', sensitive: true },
 
   // engine
-  { scope: 'engine:invoke', description: 'Start sessions and stream from the active AI engine.' },
+  { scope: 'engine:invoke', description: 'Start sessions and stream from the active AI engine.', sensitive: true },
   { scope: 'engine:register_mcp', description: 'Register additional MCP servers with the engine.', sensitive: true },
 
   // shell chrome