kenobi-pages 0.1.1 → 0.1.3

package/bin/cli.mjs

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
-var C=Object.defineProperty;var t=(e,o)=>C(e,"name",{value:o,configurable:!0});import{existsSync as P,mkdirSync as F,readFileSync as E,writeFileSync as I,appendFileSync as G}from"node:fs";import{readFile as j}from"node:fs/promises";import{homedir as L}from"node:os";import{join as _,resolve as x}from"node:path";import{createInterface as R}from"node:readline";var U="https://kenobi.ai",v=_(L(),".kenobi"),S=_(v,"config.json"),l="KENOBI_PAGES_KEY",$=t(()=>{try{return JSON.parse(E(S,"utf-8"))}catch{return{}}},"readGlobalConfig"),B=t(e=>{F(v,{recursive:!0}),I(S,JSON.stringify(e,null,2)+`
-`)},"writeGlobalConfig"),J=t(()=>{let e=process.env[l]||$().apiKey;return e||(console.error("Error: No API key found."),console.error(""),console.error("Run 'npx kenobi-pages init' to set up your API key."),console.error(""),console.error("Or set the KENOBI_PAGES_KEY environment variable directly."),process.exit(1)),e},"getApiKey"),T=t(()=>(process.env.KENOBI_BASE_URL??$().baseUrl??U).replace(/\/+$/,""),"getBaseUrl"),k=t(async(e,o={})=>{let n=`${T()}${e}`,s=await fetch(n,{method:o.method??"GET",headers:{"x-kenobi-key":J(),"Content-Type":"application/json"},body:o.body?JSON.stringify(o.body):void 0});if(!s.ok){let r=await s.text().catch(()=>"Unknown error"),i=s.status===401||s.status===403?4:s.status===404?3:1;console.error(`Error ${s.status}: ${r}`),process.exit(i)}return s.json()},"fetchKenobi"),w=t(e=>new Promise(o=>{let n=R({input:process.stdin,output:process.stderr});n.question(e,s=>{n.close(),o(s.trim())})}),"prompt"),Y=t(()=>new Promise((e,o)=>{let n="";process.stdin.setEncoding("utf-8"),process.stdin.on("data",s=>{n+=s}),process.stdin.on("end",()=>e(n)),process.stdin.on("error",o),process.stdin.isTTY&&e("")}),"readStdin"),W=t(async e=>{let o=e.indexOf("--file");return o!==-1&&e[o+1]?j(e[o+1],"utf-8"):null},"parseFileArg"),D=t(async()=>{console.error("Kenobi Pages \u2014 Setup"),console.error(""),console.error("Find your Pages API key in the workflow builder:"),console.error("  https://kenobi.ai/testing/cortex"),console.error("");let e=await w("Paste your API key (pk_live_... or pk_test_...): ");e||(console.error("No key provided. Aborting."),process.exit(1)),!e.startsWith("pk_live_")&&!e.startsWith("pk_test_")&&(console.error(`Warning: "${e}" doesn't look like a Kenobi public key (expected pk_live_... or pk_test_...).`),(await w("Continue anyway? (y/N): ")).toLowerCase()!=="y"&&(console.error("Aborting."),process.exit(1)));let o=$();o.apiKey=e,B(o),console.error(`\u2713 Saved to ${S}`);let n=x(process.cwd(),".env.local"),s=x(process.cwd(),".env"),r=P(n)?n:P(s)?s:null;if(r){let i=E(r,"utf-8");if(i.includes(l))console.error(`\u2713 ${l} already present in ${r.split("/").pop()}`);else{let p=i.endsWith(`
+var K=Object.defineProperty;var t=(e,o)=>K(e,"name",{value:o,configurable:!0});import{existsSync as O,mkdirSync as L,readFileSync as A,writeFileSync as x,appendFileSync as F}from"node:fs";import{readFile as R}from"node:fs/promises";import{homedir as G}from"node:os";import{join as P,resolve as $}from"node:path";import{createInterface as T}from"node:readline";var j="https://kenobi.ai",v=P(G(),".kenobi"),S=P(v,"config.json"),g="KENOBI_PAGES_KEY",E=t(()=>{try{return JSON.parse(A(S,"utf-8"))}catch{return{}}},"readGlobalConfig"),U=t(e=>{L(v,{recursive:!0}),x(S,JSON.stringify(e,null,2)+`
+`)},"writeGlobalConfig"),J=t(()=>{let e=process.env[g]||E().apiKey;return e||(console.error("Error: No API key found."),console.error(""),console.error("Run 'npx kenobi-pages init' to set up your API key."),console.error(""),console.error("Or set the KENOBI_PAGES_KEY environment variable directly."),process.exit(1)),e},"getApiKey"),B=t(()=>(process.env.KENOBI_BASE_URL??E().baseUrl??j).replace(/\/+$/,""),"getBaseUrl"),d=t(async(e,o={})=>{let n=`${B()}${e}`,s=await fetch(n,{method:o.method??"GET",headers:{"x-kenobi-key":J(),"Content-Type":"application/json"},body:o.body?JSON.stringify(o.body):void 0});if(!s.ok){let r=await s.text().catch(()=>"Unknown error"),i=s.status===401||s.status===403?4:s.status===404?3:1;console.error(`Error ${s.status}: ${r}`),process.exit(i)}return s.json()},"fetchKenobi"),b=t(e=>new Promise(o=>{let n=T({input:process.stdin,output:process.stderr});n.question(e,s=>{n.close(),o(s.trim())})}),"prompt"),Y=t(()=>new Promise((e,o)=>{let n="";process.stdin.setEncoding("utf-8"),process.stdin.on("data",s=>{n+=s}),process.stdin.on("end",()=>e(n)),process.stdin.on("error",o),process.stdin.isTTY&&e("")}),"readStdin"),D=t(async e=>{let o=e.indexOf("--file");return o!==-1&&e[o+1]?R(e[o+1],"utf-8"):null},"parseFileArg"),M=t(async()=>{console.error("Kenobi Pages \u2014 Setup"),console.error(""),console.error("Find your Pages API key in the workflow builder:"),console.error("  https://kenobi.ai/testing/cortex"),console.error("");let e=await b("Paste your API key (pk_live_... or pk_test_...): ");e||(console.error("No key provided. Aborting."),process.exit(1)),!e.startsWith("pk_live_")&&!e.startsWith("pk_test_")&&(console.error(`Warning: "${e}" doesn't look like a Kenobi public key (expected pk_live_... or pk_test_...).`),(await b("Continue anyway? (y/N): ")).toLowerCase()!=="y"&&(console.error("Aborting."),process.exit(1)));let o=E();o.apiKey=e,U(o),console.error(`\u2713 Saved to ${S}`);let n=$(process.cwd(),".env.local"),s=$(process.cwd(),".env"),r=O(n)?n:O(s)?s:null;if(r){let i=A(r,"utf-8");if(i.includes(g))console.error(`\u2713 ${g} already present in ${r.split("/").pop()}`);else{let a=i.endsWith(`
 `)?"":`
-`;G(r,`${p}${l}="${e}"
-`),console.error(`\u2713 Added ${l} to ${r.split("/").pop()}`)}}else(await w("No .env.local found. Create one with your API key? (Y/n): ")).toLowerCase()!=="n"&&(I(n,`${l}="${e}"
-`),console.error(`\u2713 Created .env.local with ${l}`));console.error(""),console.error("Done! You can now use kenobi-pages commands."),console.error(`  npx kenobi-pages schema push "My Page" '{"fields":{...}}'`),console.error("  npx kenobi-pages types <workflowId>")},"initCommand"),M=t(async e=>{let o=e[0];o||(console.error("Usage: kenobi-pages schema get <workflowId>"),process.exit(2));let n=await k(`/api/v1/pages/${o}/schema`);console.log(JSON.stringify(n,null,2))},"schemaGet"),q=t(async e=>{let o=e[0];o||(console.error("Usage: kenobi-pages schema push <name> '<json>'"),console.error("       kenobi-pages schema push <name> --file schema.json"),console.error("       echo '<json>' | kenobi-pages schema push <name>"),process.exit(2));let n=e.slice(1),s=await W(n),r=s?null:n.find(b=>b.startsWith("{")),i=!s&&!r?await Y():null,p=s??r??i;(!p||p.trim().length===0)&&(console.error("Error: No schema provided."),console.error("Pass inline JSON, --file <path>, or pipe to stdin."),process.exit(2));let f;try{f=JSON.parse(p)}catch{console.error("Error: Invalid JSON."),process.exit(2)}let m=await k("/api/v1/pages/schema",{method:"POST",body:{name:o,schema:f}});console.log(JSON.stringify(m,null,2)),console.error(`Schema "${m.name}" pushed successfully.`),console.error(`Source key: ${m.sourceKey}`),console.error("You can now select this schema as an output target in the Kenobi workflow builder.")},"schemaPush"),z=t(async e=>{let[o,n]=e;(!o||!n)&&(console.error("Usage: kenobi-pages page get <workflowId> <slug>"),process.exit(2));let s=await k(`/api/v1/pages/${o}/${n}`);console.log(JSON.stringify(s,null,2))},"pageGet"),H=t(async e=>{let o=e[0];o||(console.error("Usage: kenobi-pages types <workflowId>"),process.exit(2));let n=await k(`/api/v1/pages/${o}/schema`),s=n.schema;s?.fields||(console.error("Error: Workflow has no output schema with fields."),process.exit(1));let r=t(a=>"  ".repeat(a),"indent"),i=t((a,c=1)=>{switch(a.type){case"string":case"url":return"string";case"number":return"number";case"boolean":return"boolean";case"enum":return a.values?.length?a.values.map(u=>`"${u}"`).join(" | "):"string";case"object":{let u=Object.entries(a.fields??{});return u.length===0?"Record<string, unknown>":`{
-${u.map(([N,O])=>{let K=O.optional?"?":"";return`${r(c)}${N}${K}: ${i(O,c+1)}`}).join(`
+`;F(r,`${a}${g}="${e}"
+`),console.error(`\u2713 Added ${g} to ${r.split("/").pop()}`)}}else(await b("No .env.local found. Create one with your API key? (Y/n): ")).toLowerCase()!=="n"&&(x(n,`${g}="${e}"
+`),console.error(`\u2713 Created .env.local with ${g}`));console.error(""),console.error("Done! You can now use kenobi-pages commands."),console.error(`  npx kenobi-pages schema push "My Page" '{"fields":{...}}'`),console.error("  npx kenobi-pages types <workflowId>")},"initCommand"),W=t(async e=>{let o=e[0];o||(console.error("Usage: kenobi-pages schema get <workflowId>"),process.exit(2));let n=await d(`/api/v1/pages/${o}/schema`);console.log(JSON.stringify(n,null,2))},"schemaGet"),H=t(async e=>{let o=e[0];o||(console.error("Usage: kenobi-pages schema push <name> '<json>'"),console.error("       kenobi-pages schema push <name> --file schema.json"),console.error("       echo '<json>' | kenobi-pages schema push <name>"),process.exit(2));let n=e.slice(1),s=await D(n),r=s?null:n.find(y=>y.startsWith("{")),i=!s&&!r?await Y():null,a=s??r??i;(!a||a.trim().length===0)&&(console.error("Error: No schema provided."),console.error("Pass inline JSON, --file <path>, or pipe to stdin."),process.exit(2));let f;try{f=JSON.parse(a)}catch{console.error("Error: Invalid JSON."),process.exit(2)}let c=await d("/api/v1/pages/schema",{method:"POST",body:{name:o,schema:f}});console.log(JSON.stringify(c,null,2)),console.error(`Schema "${c.name}" pushed successfully.`),console.error(`Source key: ${c.sourceKey}`),console.error("You can now select this schema as an output target in the Kenobi workflow builder.")},"schemaPush"),q=t(async e=>{let[o,n]=e;(!o||!n)&&(console.error("Usage: kenobi-pages page get <workflowId> <slug>"),process.exit(2));let s=await d(`/api/v1/pages/${o}/${n}`);console.log(JSON.stringify(s,null,2))},"pageGet"),z=t(async e=>{let o=e[0];o||(console.error("Usage: kenobi-pages types <workflowId>"),process.exit(2));let n=await d(`/api/v1/pages/${o}/schema`),s=n.schema;s?.fields||(console.error("Error: Workflow has no output schema with fields."),process.exit(1));let r=t(l=>"  ".repeat(l),"indent"),i=t((l,p=1)=>{switch(l.type){case"string":case"url":return"string";case"number":return"number";case"boolean":return"boolean";case"enum":return l.values?.length?l.values.map(m=>`"${m}"`).join(" | "):"string";case"object":{let m=Object.entries(l.fields??{});return m.length===0?"Record<string, unknown>":`{
+${m.map(([N,I])=>{let C=I.optional?"?":"";return`${r(p)}${N}${C}: ${i(I,p+1)}`}).join(`
 `)}
-${r(c-1)}}`}case"array":return`Array<${i(a.items,c)}>`;default:return"unknown"}},"fieldToTs"),f=Object.entries(s.fields).map(([a,c])=>{let u=c.optional?"?":"";return`${c.description?`  /** ${c.description} */
-`:""}  ${a}${u}: ${i(c,2)}`}),b=`export interface ${n.title?n.title.replace(/[^a-zA-Z0-9]+/g,""):"PageContent"} {
+${r(p-1)}}`}case"array":return`Array<${i(l.items,p)}>`;default:return"unknown"}},"fieldToTs"),f=Object.entries(s.fields).map(([l,p])=>{let m=p.optional?"?":"";return`${p.description?`  /** ${p.description} */
+`:""}  ${l}${m}: ${i(p,2)}`}),y=`export interface ${n.title?n.title.replace(/[^a-zA-Z0-9]+/g,""):"PageContent"} {
 ${f.join(`
 `)}
 }
-`;console.log(b)},"typesGen"),V=`kenobi-pages \u2014 Kenobi Pages CLI
+`;console.log(y)},"typesGen"),V=new Set(["COMPLETED","FAILED","CANCELED","SYSTEM_FAILURE","CRASHED"]),X=t(e=>new Promise(o=>setTimeout(o,e)),"sleep"),Z=t(async e=>{let o=e[0];o||(console.error("Usage: kenobi-pages run <workflowId> [--params '<json>']"),process.exit(2));let n=e.slice(1),s=n.indexOf("--params"),r={};if(s!==-1&&n[s+1])try{r=JSON.parse(n[s+1])}catch{console.error("Error: Invalid JSON in --params"),process.exit(2)}let i=await d(`/api/v1/workflows/${o}/run`,{method:"POST",body:{params:r}});console.error(`Run triggered: ${i.runId}`),console.error("Polling for completion...");let a=2e3,f=15e3;for(;;){await X(a);let c=await d(`/api/v1/workflows/${o}/runs/${i.runId}`);if(console.error(`  Status: ${c.status}`),V.has(c.status)){console.log(JSON.stringify(c,null,2)),c.status!=="COMPLETED"&&process.exit(1);return}a=Math.min(a*1.5,f)}},"runWorkflow"),Q=t(async()=>{let e=await d("/api/v1/workflows");console.log(JSON.stringify(e,null,2))},"listWorkflows"),ee=`kenobi-pages \u2014 Kenobi Pages CLI
 
 Commands:
   kenobi-pages init                              Set up your API key (interactive)
@@ -21,6 +21,8 @@ Commands:
   kenobi-pages schema push <name> --file f       Push a schema to Kenobi (from file)
   kenobi-pages page get <workflowId> <slug>      Fetch page content for a specific lead
   kenobi-pages types <workflowId>                Generate TypeScript interface from schema
+  kenobi-pages workflows                         List workflows for your org
+  kenobi-pages run <workflowId> [--params '{}']  Trigger a workflow run and poll to completion
 
 Examples:
   npx kenobi-pages init
@@ -28,6 +30,8 @@ Examples:
   npx kenobi-pages schema push "My Page" '{"fields":{"headline":{"type":"string"}}}'
   npx kenobi-pages types 42 > lib/kenobi-types.ts
   npx kenobi-pages page get 42 acme-corp
+  npx kenobi-pages workflows
+  npx kenobi-pages run 42 --params '{"slug":"acme-corp"}'
 
 Output:
   All data is written as JSON to stdout. Status messages go to stderr.
@@ -47,4 +51,4 @@ Environment:
 Key resolution order:
   1. KENOBI_PAGES_KEY environment variable
   2. ~/.kenobi/config.json (written by 'init')
-`,[,,...d]=process.argv;(d.length===0||d[0]==="--help"||d[0]==="-h")&&(console.log(V),process.exit(0));var[g,h,...y]=d;g==="init"?await D():g==="schema"&&h==="get"?await M(y):g==="schema"&&h==="push"?await q(y):g==="page"&&h==="get"?await z(y):g==="types"?await H([h,...y]):(console.error(`Unknown command: ${d.join(" ")}`),console.error("Run 'kenobi-pages --help' for usage."),process.exit(1));
+`,[,,...h]=process.argv;(h.length===0||h[0]==="--help"||h[0]==="-h")&&(console.log(ee),process.exit(0));var[u,w,...k]=h;u==="init"?await M():u==="schema"&&w==="get"?await W(k):u==="schema"&&w==="push"?await H(k):u==="page"&&w==="get"?await q(k):u==="types"?await z([w,...k]):u==="workflows"?await Q():u==="run"?await Z([w,...k].filter(Boolean)):(console.error(`Unknown command: ${h.join(" ")}`),console.error("Run 'kenobi-pages --help' for usage."),process.exit(1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kenobi-pages",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Kenobi Pages SDK — fetch personalized page content from Kenobi workflows",
   "type": "module",
   "exports": {

package/src/cli.ts

@@ -331,6 +331,74 @@ const typesGen = async (args: string[]) => {
   console.log(output)
 }
 
+// ── Run workflow ──
+
+const TERMINAL_STATUSES = new Set(["COMPLETED", "FAILED", "CANCELED", "SYSTEM_FAILURE", "CRASHED"])
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
+
+const runWorkflow = async (args: string[]) => {
+  const workflowId = args[0]
+  if (!workflowId) {
+    console.error("Usage: kenobi-pages run <workflowId> [--params '<json>']")
+    process.exit(2)
+  }
+
+  const remaining = args.slice(1)
+  const paramsIdx = remaining.indexOf("--params")
+  let params: Record<string, string> = {}
+  if (paramsIdx !== -1 && remaining[paramsIdx + 1]) {
+    try {
+      params = JSON.parse(remaining[paramsIdx + 1]) as Record<string, string>
+    } catch {
+      console.error("Error: Invalid JSON in --params")
+      process.exit(2)
+    }
+  }
+
+  const handle = (await fetchKenobi(`/api/v1/workflows/${workflowId}/run`, {
+    method: "POST",
+    body: { params },
+  })) as { runId: string; status: string }
+
+  console.error(`Run triggered: ${handle.runId}`)
+  console.error("Polling for completion...")
+
+  let delay = 2000
+  const MAX_DELAY = 15000
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    await sleep(delay)
+    const status = (await fetchKenobi(
+      `/api/v1/workflows/${workflowId}/runs/${handle.runId}`
+    )) as { runId: string; status: string; output?: unknown; finishedAt?: string }
+
+    console.error(`  Status: ${status.status}`)
+
+    if (TERMINAL_STATUSES.has(status.status)) {
+      console.log(JSON.stringify(status, null, 2))
+      if (status.status !== "COMPLETED") process.exit(1)
+      return
+    }
+
+    delay = Math.min(delay * 1.5, MAX_DELAY)
+  }
+}
+
+const listWorkflows = async () => {
+  const data = (await fetchKenobi("/api/v1/workflows")) as {
+    workflows: Array<{
+      id: number
+      name: string
+      slug: string
+      params: Array<{ name: string; description?: string }>
+    }>
+  }
+
+  console.log(JSON.stringify(data, null, 2))
+}
+
 // ── Router ──
 
 const HELP = `kenobi-pages — Kenobi Pages CLI
@@ -342,6 +410,8 @@ Commands:
   kenobi-pages schema push <name> --file f       Push a schema to Kenobi (from file)
   kenobi-pages page get <workflowId> <slug>      Fetch page content for a specific lead
   kenobi-pages types <workflowId>                Generate TypeScript interface from schema
+  kenobi-pages workflows                         List workflows for your org
+  kenobi-pages run <workflowId> [--params '{}']  Trigger a workflow run and poll to completion
 
 Examples:
   npx kenobi-pages init
@@ -349,6 +419,8 @@ Examples:
   npx kenobi-pages schema push "My Page" '{"fields":{"headline":{"type":"string"}}}'
   npx kenobi-pages types 42 > lib/kenobi-types.ts
   npx kenobi-pages page get 42 acme-corp
+  npx kenobi-pages workflows
+  npx kenobi-pages run 42 --params '{"slug":"acme-corp"}'
 
 Output:
   All data is written as JSON to stdout. Status messages go to stderr.
@@ -389,6 +461,10 @@ if (group === "init") {
   await pageGet(rest)
 } else if (group === "types") {
   await typesGen([action, ...rest])
+} else if (group === "workflows") {
+  await listWorkflows()
+} else if (group === "run") {
+  await runWorkflow([action, ...rest].filter(Boolean))
 } else {
   console.error(`Unknown command: ${argv.join(" ")}`)
   console.error("Run 'kenobi-pages --help' for usage.")

package/src/client.ts

@@ -7,6 +7,10 @@ import type {
   KenobiPageSchema,
   KenobiSchemaResponse,
   PostSchemaResponse,
+  RunHandle,
+  RunStatusResponse,
+  WorkflowDetail,
+  WorkflowSummary,
 } from "./types"
 
 const DEFAULT_BASE_URL = "https://kenobi.ai"
@@ -38,7 +42,7 @@ const fetchFromKenobi = async (
   if (opts?.revalidate !== undefined || opts?.tags) {
     fetchInit.next = {}
     if (opts.revalidate !== undefined) fetchInit.next.revalidate = opts.revalidate
-    if (opts.tags) fetchInit.next.tags = opts.tags
+    if (opts.tags) fetchInit.next.tags = [...opts.tags]
   }
 
   const response = await fetch(url, fetchInit)
@@ -93,4 +97,31 @@ export const createKenobiPagesClient = (config: KenobiPagesConfig): KenobiPagesC
     })
     return (await response.json()) as PostSchemaResponse
   },
+
+  listWorkflows: async (): Promise<readonly WorkflowSummary[]> => {
+    const response = await fetchFromKenobi(config, "/api/v1/workflows")
+    const data = (await response.json()) as { workflows: WorkflowSummary[] }
+    return data.workflows
+  },
+
+  getWorkflow: async (workflowId: number): Promise<WorkflowDetail> => {
+    const response = await fetchFromKenobi(config, `/api/v1/workflows/${workflowId}`)
+    return (await response.json()) as WorkflowDetail
+  },
+
+  triggerRun: async (workflowId: number, params: Record<string, string>): Promise<RunHandle> => {
+    const response = await fetchFromKenobi(config, `/api/v1/workflows/${workflowId}/run`, {
+      method: "POST",
+      body: { params },
+    })
+    return (await response.json()) as RunHandle
+  },
+
+  getRunStatus: async (workflowId: number, runId: string): Promise<RunStatusResponse> => {
+    const response = await fetchFromKenobi(
+      config,
+      `/api/v1/workflows/${workflowId}/runs/${runId}`
+    )
+    return (await response.json()) as RunStatusResponse
+  },
 })

package/src/index.ts

@@ -9,4 +9,10 @@ export type {
   KenobiSchemaResponse,
   OutputFieldSpec,
   PostSchemaResponse,
+  RunHandle,
+  RunStatus,
+  RunStatusResponse,
+  WorkflowDetail,
+  WorkflowParam,
+  WorkflowSummary,
 } from "./types"

package/src/types.ts

@@ -68,6 +68,50 @@ export interface KenobiPageSchema {
   readonly fields: Readonly<Record<string, OutputFieldSpec>>
 }
 
+// ── Workflow types ──
+
+export interface WorkflowParam {
+  readonly name: string
+  readonly description?: string
+}
+
+export interface WorkflowSummary {
+  readonly id: number
+  readonly name: string
+  readonly slug: string
+  readonly params: readonly WorkflowParam[]
+  readonly outputProvider: string | null
+  readonly outputTitle: string | null
+}
+
+export interface WorkflowDetail {
+  readonly id: number
+  readonly name: string
+  readonly slug: string
+  readonly params: readonly WorkflowParam[]
+  readonly output: {
+    readonly provider: string | null
+    readonly title: string | null
+    readonly schema: Record<string, unknown> | null
+  }
+  readonly destinations: readonly { readonly adapter: string }[]
+}
+
+export interface RunHandle {
+  readonly runId: string
+  readonly status: string
+}
+
+export type RunStatus = "QUEUED" | "EXECUTING" | "COMPLETED" | "FAILED" | "CANCELED"
+
+export interface RunStatusResponse {
+  readonly runId: string
+  readonly status: RunStatus
+  readonly output: Record<string, unknown> | null
+  readonly createdAt: string
+  readonly finishedAt: string | null
+}
+
 // ── Client interface ──
 
 export interface KenobiPagesClient {
@@ -81,4 +125,8 @@ export interface KenobiPagesClient {
     opts?: KenobiFetchOptions
   ) => Promise<KenobiSchemaResponse>
   readonly postSchema: (name: string, schema: KenobiPageSchema) => Promise<PostSchemaResponse>
+  readonly listWorkflows: () => Promise<readonly WorkflowSummary[]>
+  readonly getWorkflow: (workflowId: number) => Promise<WorkflowDetail>
+  readonly triggerRun: (workflowId: number, params: Record<string, string>) => Promise<RunHandle>
+  readonly getRunStatus: (workflowId: number, runId: string) => Promise<RunStatusResponse>
 }