@zibby/skills 0.1.95 → 0.2.0

package/dist/trackers/linear-adapter.d.ts

@@ -1,89 +1,26 @@
-export namespace linearAdapter {
-    export let id: string;
-    export { toStateCategory };
-    export { toNeutral };
-    /**
-     * listCandidates — poll issues filtered by team/state/label/assignee/cursor.
-     * Linear ignores free-text `query`; pass structured filters via opts/ctx.
-     * @param {import('./types.js').ListCandidatesOptions & {ctx?: object}} [opts]
-     * @returns {Promise<import('./types.js').NeutralTicket[]>}
-     */
-    export function listCandidates(opts?: import("./types.js").ListCandidatesOptions & {
-        ctx?: object;
-    }): Promise<import("./types.js").NeutralTicket[]>;
-    /** getTicket — one issue by identifier (ENG-123) or uuid. */
-    export function getTicket(key: any): Promise<{
-        id: string;
-        key: any;
-        title: any;
-        body: any;
-        state: any;
-        stateCategory: "unknown" | "todo" | "in_progress" | "done" | "blocked";
-        assignee: any;
-        url: any;
-        _raw: any;
-    }>;
-    /** getComments — newest first. */
-    export function getComments(key: any): Promise<any>;
-    /** addComment — markdown body. */
-    export function addComment(key: any, body: any): Promise<{
-        ok: boolean;
-        id: any;
-    }>;
-    /**
-     * transition — set the issue's workflow state by target NAME. The skill
-     * resolves the name to the team's matching state id (exact → type-alias →
-     * fuzzy). No transition object in Linear.
-     */
-    export function transition(key: any, targetStateName: any): Promise<{
-        ok: boolean;
-        error: any;
-        _raw: any;
-        stateAfter?: undefined;
-        stateCategoryAfter?: undefined;
-    } | {
-        ok: boolean;
-        stateAfter: any;
-        stateCategoryAfter: "unknown" | "todo" | "in_progress" | "done" | "blocked";
-        _raw: any;
-        error?: undefined;
-    }>;
-    /**
-     * linkPullRequest — native Linear attachment; fall back to a comment.
-     */
-    export function linkPullRequest(key: any, prUrl: any, title: any): Promise<{
-        ok: boolean;
-        via: string;
-        error?: undefined;
-    } | {
-        ok: boolean;
-        via: string;
-        error: string;
-    }>;
-}
-export default linearAdapter;
-/**
- * Map a Linear state into the neutral 5-bucket category.
- * @param {{name?: string, type?: string}} [state]
- * @returns {'todo'|'in_progress'|'done'|'blocked'|'unknown'}
- */
-declare function toStateCategory(state?: {
-    name?: string;
-    type?: string;
-}): "todo" | "in_progress" | "done" | "blocked" | "unknown";
 /**
- * Build a NeutralTicket from the linear.js tool projection. The list and get
- * tools both expose `state` (name) + `stateType` (the WorkflowState type); we
- * bucket off the type, keep the raw name as `state`.
+ * Linear tracker adapter — projects Linear onto the neutral TrackerAdapter
+ * contract.
+ * ============================================================================
+ *
+ * Thin wrapper over linear.js. The skill already exposes everything we need as
+ * tools (list_issues / get_issue / get_comments / add_comment / update_state /
+ * link_attachment) and does the fuzzy state resolution internally, so the
+ * adapter is almost entirely the toNeutral mapping + plumbing.
+ *
+ * State mapping: Linear workflow states carry a `type` ∈
+ *   triage | backlog | unstarted | started | completed | canceled
+ * which maps onto the neutral buckets. Linear has no native "blocked" type, so
+ * 'blocked' is only ever derived from a state NAME match (best-effort).
+ *
+ * transition == update_state: Linear has no transition object; you set
+ * issue.stateId to any state in the same team. The skill resolves a target
+ * NAME → the team's matching state id (exact → type-alias → fuzzy).
+ *
+ * linkPullRequest == link_attachment: Linear has native attachments, the
+ * first-class way to hang a PR on an issue. Fall back to a comment if it fails.
+ *
+ * Auth/config is inherited from linear.js (LINEAR_API_KEY / LINEAR_OAUTH_TOKEN).
  */
-declare function toNeutral(issue: any): {
-    id: string;
-    key: any;
-    title: any;
-    body: any;
-    state: any;
-    stateCategory: "unknown" | "todo" | "in_progress" | "done" | "blocked";
-    assignee: any;
-    url: any;
-    _raw: any;
-};
+export declare const linearAdapter: any;
+export default linearAdapter;

package/dist/trackers/plane-adapter.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Plane tracker adapter — projects Plane onto the neutral TrackerAdapter
+ * contract. Promoted from strategy/plane-app-draft/plane-adapter.draft.js.
+ * ============================================================================
+ *
+ * Mirrors the proven shape of linear.js: ONE auth chokepoint (planeFetch, with
+ * X-API-Key), the 6 neutral methods, and a NeutralTicket with `state` (raw
+ * name), `stateCategory` (normalized bucket) and `_raw`.
+ *
+ * Plane specifics that drove the design (verified — see RESEARCH.md):
+ *   - Auth: personal access token in header `X-API-Key: <token>`. Self-hosted ⇒
+ *     base URL is the TENANT's host (https://<host>/api/v1), NOT api.plane.so.
+ *     Both come from env (same posture as linear.js).
+ *   - Scoping: every issue is workspace_slug → project_id → id. No global list,
+ *     so the adapter is bound to a (workspace, project) via env or per-call ctx.
+ *   - States carry a `group` ∈ {backlog, unstarted, started, completed,
+ *     cancelled} — the normalization key. NO transition object: you PATCH the
+ *     work-item `state` to a target state uuid (like Linear, unlike Jira).
+ *   - List endpoints are cursor-paginated:
+ *       { results, next_cursor, prev_cursor, count, total_results, ... }
+ *     per_page default & max 100; cursor format "value:offset:is_prev".
+ *   - Comments are HTML (comment_html), NOT markdown. We wrap plaintext.
+ *
+ * HONEST TODOs (inline) are Plane-version-specific details not fully confirmable
+ * from the public docs without a live instance — kept from the research draft.
+ */
 /**
  * Low-level Plane REST helper — the SINGLE auth chokepoint (cf. linearFetch).
  * Keep token + base-url resolution here; never re-implement at call sites.
@@ -8,94 +34,12 @@
  * @param {{method?:string, body?:any, query?:object, headers?:object}} [opts]
  * @returns {Promise<any>} parsed JSON (or {} for empty body)
  */
-export function planeFetch(path: string, opts?: {
-    method?: string;
-    body?: any;
-    query?: object;
-    headers?: object;
-}): Promise<any>;
+export declare function planeFetch(path: any, opts?: any): Promise<any>;
 /**
  * Normalize a Plane state into the neutral 5-bucket category.
  * @param {{name?:string, group?:string}} [state]
  * @returns {'todo'|'in_progress'|'done'|'blocked'|'unknown'}
  */
-export function toStateCategory(state?: {
-    name?: string;
-    group?: string;
-}): "todo" | "in_progress" | "done" | "blocked" | "unknown";
-export namespace planeAdapter {
-    export let id: string;
-    export let envKeys: string[];
-    export { planeFetch };
-    export { toStateCategory };
-    /**
-     * listCandidates — poll work items for a (workspace, project).
-     * @param {import('./types.js').ListCandidatesOptions & {ctx?: object}} [opts]
-     * @returns {Promise<import('./types.js').NeutralTicket[]>}
-     */
-    export function listCandidates(opts?: import("./types.js").ListCandidatesOptions & {
-        ctx?: object;
-    }): Promise<import("./types.js").NeutralTicket[]>;
-    /**
-     * getTicket — one work item by uuid (Plane addresses work items by uuid, NOT
-     * by the PROJ-42 human key).
-     * TODO: if `key` looks like "PROJ-42", resolve sequence_id → uuid via a
-     * filtered list call. For now assume a uuid.
-     */
-    export function getTicket(key: any, ctx?: {}): Promise<{
-        id: any;
-        key: any;
-        title: any;
-        body: any;
-        state: any;
-        stateCategory: "unknown" | "todo" | "in_progress" | "done" | "blocked";
-        assignee: string;
-        url: string;
-        _raw: any;
-    }>;
-    /** getComments — newest first. */
-    export function getComments(key: any, ctx?: {}): Promise<any>;
-    /**
-     * addComment — Plane comments are HTML, not markdown. We wrap plaintext in a
-     * <p> so a markdown-y body at least renders as text.
-     * TODO: confirm the API accepts comment_html on POST (vs comment_stripped),
-     * and whether it sanitizes/strips.
-     */
-    export function addComment(key: any, body: any, ctx?: {}): Promise<{
-        ok: boolean;
-        id: any;
-        _raw: any;
-    }>;
-    /**
-     * transition — Plane has NO transition object (like Linear). Resolve the
-     * target state NAME (or a neutral category word) to the project's matching
-     * state uuid, then PATCH work-item { state: <uuid> }.
-     */
-    export function transition(key: any, targetStateName: any, ctx?: {}): Promise<{
-        ok: boolean;
-        error: string;
-        availableStates: any;
-        stateAfter?: undefined;
-        stateCategoryAfter?: undefined;
-        _raw?: undefined;
-    } | {
-        ok: boolean;
-        stateAfter: any;
-        stateCategoryAfter: "unknown" | "todo" | "in_progress" | "done" | "blocked";
-        _raw: any;
-        error?: undefined;
-        availableStates?: undefined;
-    }>;
-    /**
-     * linkPullRequest — Plane has no first-class "attachment URL on issue" like
-     * Linear's attachmentCreate. The portable path is a comment with the link.
-     * (Plane does have a GitHub *integration* for repo-level linking, but that's
-     * an installed integration, not a per-issue API write.)
-     * TODO: if a target Plane exposes a link/attachment endpoint, prefer it.
-     */
-    export function linkPullRequest(key: any, prUrl: any, title: any, ctx?: {}): Promise<{
-        ok: boolean;
-        via: string;
-    }>;
-}
+export declare function toStateCategory(state: any): any;
+export declare const planeAdapter: any;
 export default planeAdapter;

package/dist/trackers/plane-adapter.js

@@ -1 +1 @@
-var f=(process.env.PLANE_API_URL||"https://api.plane.so/api/v1").replace(/\/+$/,""),A=process.env.PLANE_WORKSPACE_SLUG||"",w=process.env.PLANE_PROJECT_ID||"";function k(){let e=process.env.PLANE_API_KEY||process.env.PLANE_OAUTH_TOKEN;if(!e)throw new Error("Plane is not connected: set PLANE_API_KEY (personal access token).");return e}function p(e={}){let t=e.workspaceSlug||A,o=e.projectId||w;if(!t||!o)throw new Error("Plane scope missing: provide workspaceSlug + projectId (env PLANE_WORKSPACE_SLUG / PLANE_PROJECT_ID or per-call ctx).");return{workspaceSlug:t,projectId:o}}async function d(e,t={}){let o=`${f}${e}`;if(t.query&&Object.keys(t.query).length){let a=new URLSearchParams;for(let[c,i]of Object.entries(t.query))i!=null&&i!==""&&a.set(c,String(i));let n=a.toString();n&&(o+=(o.includes("?")?"&":"?")+n)}let r=await fetch(o,{method:t.method||"GET",headers:{"X-API-Key":k(),Accept:"application/json",...t.body?{"Content-Type":"application/json"}:{},...t.headers},body:t.body?JSON.stringify(t.body):void 0});if(!r.ok){let a=await r.text().catch(()=>"");throw new Error(`Plane API ${r.status}: ${a.slice(0,300)}`)}let s=await r.text().catch(()=>"");if(!s||!s.trim())return{};try{return JSON.parse(s)}catch{return{raw:s}}}var P={backlog:"todo",unstarted:"todo",started:"in_progress",completed:"done",cancelled:"done"},S=/\b(blocked|on[\s-]?hold|waiting|stuck)\b/i;function u(e){return e?e.name&&S.test(e.name)?"blocked":P[e.group]||"unknown":"unknown"}var m=new Map,I=300*1e3;async function g(e){let{workspaceSlug:t,projectId:o}=p(e),r=m.get(o);if(r&&Date.now()-r.fetchedAt<I)return r.states;let s=await d(`/workspaces/${encodeURIComponent(t)}/projects/${encodeURIComponent(o)}/states/`,{query:{per_page:100}}),a=(s.results||s||[]).map(n=>({id:n.id,name:n.name,group:n.group,color:n.color}));return m.set(o,{fetchedAt:Date.now(),states:a}),a}function l(e){return String(e||"").toLowerCase().replace(/\s+/g,"").replace(/[()\-_:："'`]/g,"")}function C(e,t){let o=l(t);if(!o)return null;let r=e.find(a=>l(a.name)===o);if(r)return r;let s={todo:["todo","backlog","open","unstarted"],inprogress:["inprogress","started","doing","wip"],done:["done","completed","closed","resolved","cancelled","canceled"],blocked:["blocked","onhold","waiting"]};for(let[,a]of Object.entries(s)){if(!a.some(i=>l(i)===o))continue;let n=o==="done"?"completed":o==="inprogress"?"started":"unstarted",c=e.find(i=>i.group===n);if(c)return c}return null}async function _(e,t){let r=(await g(t).catch(()=>[])).find(i=>i.id===e.state)||null,{workspaceSlug:s,projectId:a}=p(t),n=t.projectIdentifier&&e.sequence_id!=null?`${t.projectIdentifier}-${e.sequence_id}`:e.sequence_id!=null?String(e.sequence_id):e.id,c=e.assignees||[];return{id:e.id,key:n,title:e.name||"",body:e.description_html||e.description_stripped||e.description||"",state:r?r.name:null,stateCategory:u(r),assignee:c.length?String(c[0]):null,url:t.baseWebUrl?`${t.baseWebUrl}/${s}/projects/${a}/issues/${e.id}`:null,_raw:e}}var E={id:"plane",envKeys:["PLANE_API_KEY","PLANE_OAUTH_TOKEN","PLANE_API_URL","PLANE_WORKSPACE_SLUG","PLANE_PROJECT_ID"],planeFetch:d,toStateCategory:u,async listCandidates(e={}){let t=e.ctx||{},{workspaceSlug:o,projectId:r}=p(t),s={per_page:Math.min(Number(e.limit)||50,100),cursor:e.cursor};e.state&&(s.state=e.state),e.updatedAfter&&(s.updated_at__gte=e.updatedAfter);let n=(await d(`/workspaces/${encodeURIComponent(o)}/projects/${encodeURIComponent(r)}/work-items/`,{query:s})).results||[];return e.updatedAfter&&(n=n.filter(c=>String(c.updated_at)>String(e.updatedAfter))),Promise.all(n.map(c=>_(c,t)))},async getTicket(e,t={}){let{workspaceSlug:o,projectId:r}=p(t),s=await d(`/workspaces/${encodeURIComponent(o)}/projects/${encodeURIComponent(r)}/work-items/${encodeURIComponent(e)}/`);return!s||!s.id?null:_(s,t)},async getComments(e,t={}){let{workspaceSlug:o,projectId:r}=p(t);return((await d(`/workspaces/${encodeURIComponent(o)}/projects/${encodeURIComponent(r)}/work-items/${encodeURIComponent(e)}/comments/`,{query:{per_page:100}})).results||[]).map(n=>({id:n.id,author:n.actor||n.actor_detail?.display_name||"Unknown",body:n.comment_html||n.comment_stripped||"",createdAt:n.created_at||null,updatedAt:n.updated_at||null,_raw:n})).sort((n,c)=>String(c.createdAt).localeCompare(String(n.createdAt)))},async addComment(e,t,o={}){let{workspaceSlug:r,projectId:s}=p(o),n=/<[a-z][\s\S]*>/i.test(String(t||""))?String(t):`<p>${String(t||"")}</p>`,c=await d(`/workspaces/${encodeURIComponent(r)}/projects/${encodeURIComponent(s)}/work-items/${encodeURIComponent(e)}/comments/`,{method:"POST",body:{comment_html:n}});return{ok:!!c.id,id:c.id||null,_raw:c}},async transition(e,t,o={}){let{workspaceSlug:r,projectId:s}=p(o),a=await g(o),n=C(a,t);if(!n)return{ok:!1,error:`No Plane state matches "${t}" in this project`,availableStates:a.map(i=>({id:i.id,name:i.name,group:i.group}))};let c=await d(`/workspaces/${encodeURIComponent(r)}/projects/${encodeURIComponent(s)}/work-items/${encodeURIComponent(e)}/`,{method:"PATCH",body:{state:n.id}});return{ok:!!c.id,stateAfter:n.name,stateCategoryAfter:u(n),_raw:c}},async linkPullRequest(e,t,o,r={}){let s=o?`${o}: `:"Linked PR: ";return{ok:!!(await this.addComment(e,`<p>${s}<a href="${t}">${t}</a></p>`,r)).ok,via:"comment"}}},h=E;export{h as default,E as planeAdapter,d as planeFetch,u as toStateCategory};
+var f=(process.env.PLANE_API_URL||"https://api.plane.so/api/v1").replace(/\/+$/,""),A=process.env.PLANE_WORKSPACE_SLUG||"",w=process.env.PLANE_PROJECT_ID||"";function y(){let e=process.env.PLANE_API_KEY||process.env.PLANE_OAUTH_TOKEN;if(!e)throw new Error("Plane is not connected: set PLANE_API_KEY (personal access token).");return e}function p(e={}){let t=e.workspaceSlug||A,o=e.projectId||w;if(!t||!o)throw new Error("Plane scope missing: provide workspaceSlug + projectId (env PLANE_WORKSPACE_SLUG / PLANE_PROJECT_ID or per-call ctx).");return{workspaceSlug:t,projectId:o}}async function d(e,t={}){let o=`${f}${e}`;if(t.query&&Object.keys(t.query).length){let a=new URLSearchParams;for(let[c,i]of Object.entries(t.query))i!=null&&i!==""&&a.set(c,String(i));let n=a.toString();n&&(o+=(o.includes("?")?"&":"?")+n)}let r=await fetch(o,{method:t.method||"GET",headers:{"X-API-Key":y(),Accept:"application/json",...t.body?{"Content-Type":"application/json"}:{},...t.headers},body:t.body?JSON.stringify(t.body):void 0});if(!r.ok){let a=await r.text().catch(()=>"");throw new Error(`Plane API ${r.status}: ${a.slice(0,300)}`)}let s=await r.text().catch(()=>"");if(!s||!s.trim())return{};try{return JSON.parse(s)}catch{return{raw:s}}}var k={backlog:"todo",unstarted:"todo",started:"in_progress",completed:"done",cancelled:"done"},P=/\b(blocked|on[\s-]?hold|waiting|stuck)\b/i;function u(e){return e?e.name&&P.test(e.name)?"blocked":k[e.group]||"unknown":"unknown"}var m=new Map,S=300*1e3;async function g(e){let{workspaceSlug:t,projectId:o}=p(e),r=m.get(o);if(r&&Date.now()-r.fetchedAt<S)return r.states;let s=await d(`/workspaces/${encodeURIComponent(t)}/projects/${encodeURIComponent(o)}/states/`,{query:{per_page:100}}),a=(s.results||s||[]).map(n=>({id:n.id,name:n.name,group:n.group,color:n.color}));return m.set(o,{fetchedAt:Date.now(),states:a}),a}function l(e){return String(e||"").toLowerCase().replace(/\s+/g,"").replace(/[()\-_:："'`]/g,"")}function I(e,t){let o=l(t);if(!o)return null;let r=e.find(a=>l(a.name)===o);if(r)return r;let s={todo:["todo","backlog","open","unstarted"],inprogress:["inprogress","started","doing","wip"],done:["done","completed","closed","resolved","cancelled","canceled"],blocked:["blocked","onhold","waiting"]};for(let[,a]of Object.entries(s)){if(!a.some(i=>l(i)===o))continue;let n=o==="done"?"completed":o==="inprogress"?"started":"unstarted",c=e.find(i=>i.group===n);if(c)return c}return null}async function _(e,t){let r=(await g(t).catch(()=>[])).find(i=>i.id===e.state)||null,{workspaceSlug:s,projectId:a}=p(t),n=t.projectIdentifier&&e.sequence_id!=null?`${t.projectIdentifier}-${e.sequence_id}`:e.sequence_id!=null?String(e.sequence_id):e.id,c=e.assignees||[];return{id:e.id,key:n,title:e.name||"",body:e.description_html||e.description_stripped||e.description||"",state:r?r.name:null,stateCategory:u(r),assignee:c.length?String(c[0]):null,url:t.baseWebUrl?`${t.baseWebUrl}/${s}/projects/${a}/issues/${e.id}`:null,_raw:e}}var C={id:"plane",envKeys:["PLANE_API_KEY","PLANE_OAUTH_TOKEN","PLANE_API_URL","PLANE_WORKSPACE_SLUG","PLANE_PROJECT_ID"],planeFetch:d,toStateCategory:u,async listCandidates(e={}){let t=e.ctx||{},{workspaceSlug:o,projectId:r}=p(t),s={per_page:Math.min(Number(e.limit)||50,100),cursor:e.cursor};e.state&&(s.state=e.state),e.updatedAfter&&(s.updated_at__gte=e.updatedAfter);let n=(await d(`/workspaces/${encodeURIComponent(o)}/projects/${encodeURIComponent(r)}/work-items/`,{query:s})).results||[];return e.updatedAfter&&(n=n.filter(c=>String(c.updated_at)>String(e.updatedAfter))),Promise.all(n.map(c=>_(c,t)))},async getTicket(e,t={}){let{workspaceSlug:o,projectId:r}=p(t),s=await d(`/workspaces/${encodeURIComponent(o)}/projects/${encodeURIComponent(r)}/work-items/${encodeURIComponent(e)}/`);return!s||!s.id?null:_(s,t)},async getComments(e,t={}){let{workspaceSlug:o,projectId:r}=p(t);return((await d(`/workspaces/${encodeURIComponent(o)}/projects/${encodeURIComponent(r)}/work-items/${encodeURIComponent(e)}/comments/`,{query:{per_page:100}})).results||[]).map(n=>({id:n.id,author:n.actor||n.actor_detail?.display_name||"Unknown",body:n.comment_html||n.comment_stripped||"",createdAt:n.created_at||null,updatedAt:n.updated_at||null,_raw:n})).sort((n,c)=>String(c.createdAt).localeCompare(String(n.createdAt)))},async addComment(e,t,o={}){let{workspaceSlug:r,projectId:s}=p(o),n=/<[a-z][\s\S]*>/i.test(String(t||""))?String(t):`<p>${String(t||"")}</p>`,c=await d(`/workspaces/${encodeURIComponent(r)}/projects/${encodeURIComponent(s)}/work-items/${encodeURIComponent(e)}/comments/`,{method:"POST",body:{comment_html:n}});return{ok:!!c.id,id:c.id||null,_raw:c}},async transition(e,t,o={}){let{workspaceSlug:r,projectId:s}=p(o),a=await g(o),n=I(a,t);if(!n)return{ok:!1,error:`No Plane state matches "${t}" in this project`,availableStates:a.map(i=>({id:i.id,name:i.name,group:i.group}))};let c=await d(`/workspaces/${encodeURIComponent(r)}/projects/${encodeURIComponent(s)}/work-items/${encodeURIComponent(e)}/`,{method:"PATCH",body:{state:n.id}});return{ok:!!c.id,stateAfter:n.name,stateCategoryAfter:u(n),_raw:c}},async linkPullRequest(e,t,o,r={}){let s=o?`${o}: `:"Linked PR: ";return{ok:!!(await this.addComment(e,`<p>${s}<a href="${t}">${t}</a></p>`,r)).ok,via:"comment"}}},E=C;export{E as default,C as planeAdapter,d as planeFetch,u as toStateCategory};

package/dist/trackers/types.d.ts

@@ -147,189 +147,4 @@
  *   which path was used ('remotelink' | 'attachment' | 'comment').
  */
 /** @type {StateCategory[]} */
-export const TRACKER_STATE_CATEGORIES: StateCategory[];
-/**
- * Normalized 5-bucket state. The pipeline branches on this; never on `state`.
- */
-export type StateCategory = "todo" | "in_progress" | "done" | "blocked" | "unknown";
-/**
- * A tracker ticket/issue projected onto the neutral model.
- */
-export type NeutralTicket = {
-    /**
-     *   Stable provider-internal id. Jira: issue id (numeric string). Linear: uuid.
-     *   GitHub: issue number as a string. Plane: work-item uuid. Opaque — pass it
-     *   back to the same adapter; do not parse it.
-     */
-    id: string;
-    /**
-     *   Human-facing reference. Jira: `PROJ-123`. Linear: `ENG-12`. GitHub:
-     *   `owner/repo#123`. Plane: `PROJ-42` (or the uuid if the identifier is
-     *   unknown). This is what shows up in PR titles / comments.
-     */
-    key: string;
-    /**
-     *   Short summary line (Symphony §4 `title`).
-     */
-    title: string;
-    /**
-     *   Full description as plain text / markdown (Symphony §4 `body`). ADF/HTML is
-     *   flattened by the adapter; never raw ADF or raw HTML here.
-     */
-    body: string;
-    /**
-     *   RAW provider status NAME, exactly as the tracker spells it ("In Progress",
-     *   "Done", "started", "测试"). Use this for write-back (transition). `null`
-     *   when the provider/issue has no resolvable status.
-     */
-    state: string | null;
-    /**
-     *   Normalized bucket — what the pipeline branches on.
-     */
-    stateCategory: StateCategory;
-    /**
-     *   Single human-readable assignee (display name or login). `null` if
-     *   unassigned. Multi-assignee providers (GitHub, Plane) collapse to the first;
-     *   the full list, if any, lives in `_raw`.
-     */
-    assignee: string | null;
-    /**
-     *   Canonical web URL of the ticket, or `null` if the adapter can't derive one.
-     */
-    url: string | null;
-    /**
-     *   Escape hatch — the untouched provider payload. Read provider-specific data
-     *   (sprint, story points, cycle, milestone, sequence_id, labels…) from here.
-     *   NEVER promote a `_raw` field to a top-level neutral field.
-     */
-    _raw: any;
-};
-/**
- * A single comment on a ticket, projected onto the neutral model.
- */
-export type NeutralComment = {
-    /**
-     * Provider comment id (opaque).
-     */
-    id: string;
-    /**
-     * Human-readable author (display name/login).
-     */
-    author: string;
-    /**
-     * Comment text as plain text / markdown
-     * (ADF/HTML flattened).
-     */
-    body: string;
-    /**
-     * ISO-8601 creation timestamp, if available.
-     */
-    createdAt: string | null;
-    /**
-     * ISO-8601 update timestamp, if available.
-     */
-    updatedAt: string | null;
-    /**
-     * Untouched provider comment payload.
-     */
-    _raw?: any;
-};
-/**
- * Options accepted by {@link TrackerAdapter.listCandidates}. Every field is
- * optional; what each provider honors differs (documented per adapter). The
- * shared minimum is "give me a bounded, newest-first slab of work to consider".
- */
-export type ListCandidatesOptions = {
-    /**
-     * Provider-native query. Jira: a JQL string. GitHub: free-text issue search
-     * (or used with `labels`). Linear/Plane: ignored in favor of structured
-     * filters below. Adapters that can't honor it ignore it.
-     */
-    query?: string;
-    /**
-     * Restrict to issues carrying label(s).
-     */
-    labels?: string | string[];
-    /**
-     * Provider state filter (raw name or, for
-     *            GitHub, open|closed|all).
-     */
-    state?: string;
-    /**
-     * ISO-8601 polling cursor; only issues
-     *     updated at/after this.
-     */
-    updatedAfter?: string;
-    /**
-     * Max tickets to return (bounded).
-     */
-    limit?: number;
-    /**
-     * Opaque pagination cursor (Plane).
-     */
-    cursor?: string;
-    /**
-     * Provider scope/context (e.g. GitHub
-     *              {owner, repo}; Plane {workspaceSlug,
-     *              projectId}). Passed through verbatim.
-     */
-    ctx?: any;
-};
-/**
- * The neutral tracker interface — the 6-method MINIMUM contract.
- *
- * Three READ methods + three WRITE methods + identity metadata. Each concrete
- * adapter (jira / linear / github / plane) implements exactly these. Anything a
- * single provider can do that the others can't does NOT get a 7th method — it
- * stays accessible only via that provider's own skill tools / the `_raw` hatch.
- */
-export type TrackerAdapter = {
-    /**
-     *   Provider id: 'jira' | 'linear' | 'github' | 'plane'.
-     */
-    id: string;
-    /**
-     *   READ. Return a bounded, newest-first set of tickets to consider for work.
-     */
-    listCandidates: (opts?: ListCandidatesOptions) => Promise<NeutralTicket[]>;
-    /**
-     *   READ. Fetch one ticket by its `key` (or id). `null` if not found.
-     */
-    getTicket: (key: string, ctx?: any) => Promise<NeutralTicket | null>;
-    /**
-     *   READ. Fetch the comment thread (newest first).
-     */
-    getComments: (key: string, ctx?: any) => Promise<NeutralComment[]>;
-    /**
-     *   WRITE. Add a comment. `body` is plain text / markdown; the adapter handles
-     *   provider encoding (Jira ADF, Plane HTML).
-     */
-    addComment: (key: string, body: string, ctx?: any) => Promise<{
-        ok: boolean;
-        id?: string | null;
-        error?: string;
-    }>;
-    /**
-     *   WRITE. Move the ticket to a target state, addressed by its RAW name
-     *   (fuzzy-matched per provider). Jira performs a workflow transition; Linear /
-     *   Plane PATCH the state directly; GitHub maps to open/close (+ a labels
-     *   convention — see github-adapter). NOT every target name is reachable on
-     *   every provider; the result carries `ok:false` + `error` when it isn't.
-     */
-    transition: (key: string, targetStateName: string, ctx?: any) => Promise<{
-        ok: boolean;
-        stateAfter?: string | null;
-        stateCategoryAfter?: StateCategory;
-        error?: string;
-    }>;
-    /**
-     *   WRITE. Associate a PR URL with the ticket. Native where possible (Jira
-     *   remote-link, Linear attachment); a comment everywhere else. `via` reports
-     *   which path was used ('remotelink' | 'attachment' | 'comment').
-     */
-    linkPullRequest: (key: string, prUrl: string, title?: string, ctx?: any) => Promise<{
-        ok: boolean;
-        via?: string;
-        error?: string;
-    }>;
-};
+export declare const TRACKER_STATE_CATEGORIES: string[];

package/dist/triggerAgent.d.ts

@@ -1,42 +1,26 @@
-export namespace triggerAgentSkill {
-    let id: string;
-    let serverName: string;
-    let allowedTools: string[];
-    let envKeys: any[];
-    let description: string;
-    let promptFragment: string;
-    function resolve(): {
-        command: any;
-        args: any[];
-        env: {};
-        description: string;
-        type?: undefined;
-        alwaysLoad?: undefined;
-    } | {
-        type: string;
-        command: string;
-        args: any[];
-        env: {};
-        description: string;
-        alwaysLoad: boolean;
-    };
-    function handleToolCall(name: any, args?: {}): Promise<string>;
-    let tools: {
-        name: string;
-        description: string;
-        input_schema: {
-            type: string;
-            properties: {
-                workflowType: {
-                    type: string;
-                    description: string;
-                };
-                input: {
-                    type: string;
-                    description: string;
-                };
-            };
-            required: any[];
-        };
-    }[];
-}
+/**
+ * trigger-agent — a GENERIC, agent-callable skill for firing another Zibby
+ * agent run from inside a running agent.
+ *
+ * The agent gets ONE real MCP tool, `trigger_agent`, and DECIDES for itself
+ * when (and how many times) to call it — so a triage agent can trigger a fix for
+ * every issue it judges worth fixing, an orchestrator can fan out to N children,
+ * etc. This is the agent-driven counterpart to the engine's deterministic
+ * `dispatchSubgraph` — the primitive lives in the model's hands, not in node code.
+ *
+ * Portable across CLOUD and SELF-HOSTED (the same reason @zibby/skills/datasetStore
+ * works in both): it POSTs to `${apiBase}/projects/{PROJECT_ID}/workflows/{type}/trigger`
+ * with the run's `PROJECT_API_TOKEN`, resolving `apiBase` from the env the runtime
+ * injects — cloud sets `PROGRESS_API_URL` (`<base>/executions`), self-hosted's
+ * docker/k8s dispatcher sets `ZIBBY_ACCOUNT_API_URL` ("reachable FROM the run") —
+ * so neither environment needs a special case.
+ *
+ * Fire-and-forget: it triggers the run and returns its executionId; it does NOT
+ * wait for the child to finish. `handleToolCall` NEVER throws — any failure comes
+ * back as `{ ok:false, error }` so a bad trigger can't crash the calling agent.
+ *
+ * Shape mirrors the other hand-written multi-tool skills (github.js / datasetStore.js):
+ * `serverName`, `allowedTools`, `tools[]`, `handleToolCall`, and a `resolve()` that
+ * spawns the generic bin/mcp-skill.mjs.
+ */
+export declare const triggerAgentSkill: any;

package/dist/triggerAgent.js

@@ -1 +1 @@
-import{dirname as f,resolve as d}from"path";import{fileURLToPath as u}from"url";import{existsSync as h}from"fs";function T(){if(process.env.MCP_SKILL_PATH)return process.env.MCP_SKILL_PATH;let r=f(u(import.meta.url)),e=d(r,"..","bin","mcp-skill.mjs");return h(e)?e:null}function _(){return process.env.PROJECT_API_TOKEN||process.env.ZIBBY_USER_TOKEN||null}function w(){return((process.env.PROGRESS_API_URL||"").replace(/\/executions\/?$/,"")||process.env.ZIBBY_ACCOUNT_API_URL||process.env.ZIBBY_PROD_ACCOUNT_API_URL||(process.env.ZIBBY_ENV==="local"?"http://localhost:3001":"https://api-prod.zibby.app")).replace(/\/+$/,"")}var y={name:"trigger_agent",description:"Trigger another Zibby workflow/agent run in THIS project (fire-and-forget). Call it once per run you want to start \u2014 the agent decides which and how many. Omit workflowType to re-run THIS same agent (self-dispatch, e.g. with a different trigger input). Returns the started run's executionId; does NOT wait for it to finish.",input_schema:{type:"object",properties:{workflowType:{type:"string",description:"Which workflow to trigger (its type/slug in this project). Omit to trigger THIS same agent (self-dispatch)."},input:{type:"object",description:"The trigger payload passed to the target workflow (validated against its state schema)."}},required:[]}},k={id:"trigger-agent",serverName:"trigger",allowedTools:["mcp__trigger__*"],envKeys:[],description:"Trigger another Zibby workflow/agent run in this project (agent-driven, fire-and-forget; cloud + self-hosted).",promptFragment:"## Trigger another agent (agent-driven)\nYou can start another Zibby agent run yourself with the `trigger_agent`\ntool \u2014 and YOU decide when and how many times to call it. Each call starts ONE\nindependent run (fire-and-forget) and returns its executionId; it does NOT wait for\nthat run to finish.\n- To re-run THIS same agent (self-dispatch) \u2014 e.g. to hand an item to another of\n  this agent's scenarios \u2014 OMIT `workflowType` and pass the `input` for that run.\n- To trigger a DIFFERENT agent in the project, pass its `workflowType` + `input`.\nCall it once per run you want to start (loop over your items and call it for each).\nIt never throws \u2014 a failure comes back as { ok:false, error }; log it and move on.",resolve(){let r=T();if(!r)return{command:null,args:[],env:{},description:this.description};let e={};for(let t of["PROJECT_API_TOKEN","PROJECT_ID","WORKFLOW_TYPE","PROGRESS_API_URL","ZIBBY_ACCOUNT_API_URL","ZIBBY_PROD_ACCOUNT_API_URL","ZIBBY_ENV","ZIBBY_USER_TOKEN"])process.env[t]&&(e[t]=process.env[t]);return{type:"stdio",command:"node",args:[r,"../dist/triggerAgent.js","triggerAgentSkill"],env:e,description:this.description,alwaysLoad:!1}},async handleToolCall(r,e={}){if(r!=="trigger_agent")return JSON.stringify({ok:!1,error:`unknown tool: ${r}`});try{let t=process.env.PROJECT_ID,a=_(),s=typeof e.workflowType=="string"&&e.workflowType.trim()?e.workflowType.trim():(process.env.WORKFLOW_TYPE||"").trim();if(!t)return JSON.stringify({ok:!1,error:"PROJECT_ID not set \u2014 cannot resolve the target project."});if(!a)return JSON.stringify({ok:!1,error:"PROJECT_API_TOKEN not set \u2014 cannot authenticate the trigger."});if(!s)return JSON.stringify({ok:!1,error:"No workflowType given and WORKFLOW_TYPE is unset \u2014 nothing to trigger."});let l=`${w()}/projects/${encodeURIComponent(t)}/workflows/${encodeURIComponent(s)}/trigger`,c=new AbortController,g=setTimeout(()=>c.abort(),2e4),n;try{n=await fetch(l,{method:"POST",headers:{"content-type":"application/json",authorization:`Bearer ${a}`},body:JSON.stringify({input:e.input&&typeof e.input=="object"?e.input:{}}),signal:c.signal})}finally{clearTimeout(g)}let i=await n.text().catch(()=>""),o;try{o=i?JSON.parse(i):{}}catch{o={raw:i}}if(!n.ok)return JSON.stringify({ok:!1,error:`trigger failed (HTTP ${n.status})`,detail:o&&(o.error||o.message)||i.slice(0,300)});let p=o.executionId||o.execution?.id||o.id||null;return JSON.stringify({ok:!0,workflowType:s,executionId:p,note:"run started (fire-and-forget)"})}catch(t){return JSON.stringify({ok:!1,error:`trigger_agent failed: ${t?.message||String(t)}`})}},tools:[y]};export{k as triggerAgentSkill};
+import{dirname as f,resolve as d}from"path";import{fileURLToPath as u}from"url";import{existsSync as h}from"fs";function T(){if(process.env.MCP_SKILL_PATH)return process.env.MCP_SKILL_PATH;let r=f(u(import.meta.url)),e=d(r,"..","bin","mcp-skill.mjs");return h(e)?e:null}function y(){return process.env.PROJECT_API_TOKEN||process.env.ZIBBY_USER_TOKEN||null}function _(){return((process.env.PROGRESS_API_URL||"").replace(/\/executions\/?$/,"")||process.env.ZIBBY_ACCOUNT_API_URL||process.env.ZIBBY_PROD_ACCOUNT_API_URL||(process.env.ZIBBY_ENV==="local"?"http://localhost:3001":"https://api-prod.zibby.app")).replace(/\/+$/,"")}var w={name:"trigger_agent",description:"Trigger another Zibby workflow/agent run in THIS project (fire-and-forget). Call it once per run you want to start \u2014 the agent decides which and how many. Omit workflowType to re-run THIS same agent (self-dispatch, e.g. with a different trigger input). Returns the started run's executionId; does NOT wait for it to finish.",input_schema:{type:"object",properties:{workflowType:{type:"string",description:"Which workflow to trigger (its type/slug in this project). Omit to trigger THIS same agent (self-dispatch)."},input:{type:"object",description:"The trigger payload passed to the target workflow (validated against its state schema)."}},required:[]}},k={id:"trigger-agent",serverName:"trigger",allowedTools:["mcp__trigger__*"],envKeys:[],description:"Trigger another Zibby workflow/agent run in this project (agent-driven, fire-and-forget; cloud + self-hosted).",promptFragment:"## Trigger another agent (agent-driven)\nYou can start another Zibby agent run yourself with the `trigger_agent`\ntool \u2014 and YOU decide when and how many times to call it. Each call starts ONE\nindependent run (fire-and-forget) and returns its executionId; it does NOT wait for\nthat run to finish.\n- To re-run THIS same agent (self-dispatch) \u2014 e.g. to hand an item to another of\n  this agent's scenarios \u2014 OMIT `workflowType` and pass the `input` for that run.\n- To trigger a DIFFERENT agent in the project, pass its `workflowType` + `input`.\nCall it once per run you want to start (loop over your items and call it for each).\nIt never throws \u2014 a failure comes back as { ok:false, error }; log it and move on.",resolve(){let r=T();if(!r)return{command:null,args:[],env:{},description:this.description};let e={};for(let t of["PROJECT_API_TOKEN","PROJECT_ID","WORKFLOW_TYPE","PROGRESS_API_URL","ZIBBY_ACCOUNT_API_URL","ZIBBY_PROD_ACCOUNT_API_URL","ZIBBY_ENV","ZIBBY_USER_TOKEN"])process.env[t]&&(e[t]=process.env[t]);return{type:"stdio",command:"node",args:[r,"../dist/triggerAgent.js","triggerAgentSkill"],env:e,description:this.description,alwaysLoad:!1}},async handleToolCall(r,e={}){if(r!=="trigger_agent")return JSON.stringify({ok:!1,error:`unknown tool: ${r}`});try{let t=process.env.PROJECT_ID,a=y(),s=typeof e.workflowType=="string"&&e.workflowType.trim()?e.workflowType.trim():(process.env.WORKFLOW_TYPE||"").trim();if(!t)return JSON.stringify({ok:!1,error:"PROJECT_ID not set \u2014 cannot resolve the target project."});if(!a)return JSON.stringify({ok:!1,error:"PROJECT_API_TOKEN not set \u2014 cannot authenticate the trigger."});if(!s)return JSON.stringify({ok:!1,error:"No workflowType given and WORKFLOW_TYPE is unset \u2014 nothing to trigger."});let l=`${_()}/projects/${encodeURIComponent(t)}/workflows/${encodeURIComponent(s)}/trigger`,c=new AbortController,g=setTimeout(()=>c.abort(),2e4),n;try{n=await fetch(l,{method:"POST",headers:{"content-type":"application/json",authorization:`Bearer ${a}`},body:JSON.stringify({input:e.input&&typeof e.input=="object"?e.input:{}}),signal:c.signal})}finally{clearTimeout(g)}let i=await n.text().catch(()=>""),o;try{o=i?JSON.parse(i):{}}catch{o={raw:i}}if(!n.ok)return JSON.stringify({ok:!1,error:`trigger failed (HTTP ${n.status})`,detail:o&&(o.error||o.message)||i.slice(0,300)});let p=o.executionId||o.execution?.id||o.id||null;return JSON.stringify({ok:!0,workflowType:s,executionId:p,note:"run started (fire-and-forget)"})}catch(t){return JSON.stringify({ok:!1,error:`trigger_agent failed: ${t?.message||String(t)}`})}},tools:[w]};export{k as triggerAgentSkill};