@ekanos/cli 0.12.0 → 0.14.0

package/dist/routes-api.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { request } from './auth/ekanos-api.js';
-import { authRequiredError, forbiddenError, networkError, notFoundError, usageError, } from './errors.js';
+import { authRequiredError, forbiddenError, invalidStateError, networkError, notFoundError, usageError, } from './errors.js';
 /**
  * The CLI's client for a Source's event routing (plan 241.4): which team each
  * value of an integration's route key (Zendesk's organization) belongs to,
@@ -10,7 +10,7 @@ import { authRequiredError, forbiddenError, networkError, notFoundError, usageEr
  *   PUT    /api/partner/routes/<product>?source=<slug>   { value, team, label? }
  *   DELETE /api/partner/routes/<product>?source=<slug>&value=<value>
  *   GET    /api/partner/routes/<product>/options?source=<slug>
- *   POST   /api/partner/routes/<product>/webhook?source=<slug>[&webhook=<id>]
+ *   POST   /api/partner/routes/<product>/webhook?source=<slug>[&webhook=<id>][&replace=true]
  *   GET    /api/partner/routes/unrouted?source=<slug>[&product=<slug>]
  *   POST   /api/partner/routes/unrouted/<id>/replay?source=<slug>
  *
@@ -18,7 +18,7 @@ import { authRequiredError, forbiddenError, networkError, notFoundError, usageEr
  *   → 403 { code: "SOURCE_ADMIN_REQUIRED" | "MFA_REQUIRED" | "FORBIDDEN" }
  *   → 404 { code: "PRODUCT_NOT_ENTITLED" | "TEAM_NOT_FOUND" | "ROUTE_NOT_FOUND"
  *               | "EVENT_NOT_FOUND" | "SOURCE_NOT_FOUND" }
- *   → 409 { code: "NO_ROUTING" | "NO_WEBHOOK" }
+ *   → 409 { code: "NO_ROUTING" | "NO_WEBHOOK" | "WEBHOOK_LIVE" }
  *
  * The contract's shapes live here rather than in `@ekanos/integration-schema`,
  * so the routing commands ship with the CLI alone.
@@ -61,6 +61,8 @@ export const RouteWebhookSchema = z.object({
     signature: z
         .object({ header: z.string(), secretName: z.string() })
         .nullable(),
+    /** A live URL was revoked by this mint. An older host does not say. */
+    replaced: z.boolean().optional(),
 });
 const UnroutedEventSchema = z.object({
     id: z.string(),
@@ -78,7 +80,7 @@ export const ReplaySchema = z.object({
 });
 const BASE = '/api/partner/routes';
 export async function routesCall(host, accessToken, schema, init) {
-    var _a;
+    var _a, _b;
     const query = Object.fromEntries(Object.entries(init.query).filter((entry) => entry[1] !== undefined));
     const url = `${host}${BASE}${(_a = init.path) !== null && _a !== void 0 ? _a : ''}?${new URLSearchParams(query)}`;
     const response = await request(url, {
@@ -114,6 +116,9 @@ export async function routesCall(host, accessToken, schema, init) {
                         ? 'Run "ekanos catalog" to see what the Source has.'
                         : 'Run "ekanos sources" to list the sources you hold a seat on.');
     }
+    if (response.status === 409 && code === 'WEBHOOK_LIVE') {
+        throw invalidStateError(message !== null && message !== void 0 ? message : 'The Source already has a live webhook URL.', (_b = init.confirmHint) !== null && _b !== void 0 ? _b : 'Re-run with --yes when you are ready to update the vendor.');
+    }
     if (response.status === 409) {
         throw usageError(message !== null && message !== void 0 ? message : 'The integration does not route events.', code === 'NO_WEBHOOK'
             ? 'Name the webhook: "ekanos routes webhook <product> --webhook <id>".'

package/dist/routes-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"routes-api.js","sourceRoot":"","sources":["../src/routes-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\nimport { request } from './auth/ekanos-api';\nimport {\n  authRequiredError,\n  forbiddenError,\n  networkError,\n  notFoundError,\n  usageError,\n} from './errors';\n\n/**\n * The CLI's client for a Source's event routing (plan 241.4): which team each\n * value of an integration's route key (Zendesk's organization) belongs to,\n * the Source's webhook endpoint, and the events no team is mapped to yet.\n *\n *   GET    /api/partner/routes?source=<slug>[&product=<slug>]\n *   PUT    /api/partner/routes/<product>?source=<slug>   { value, team, label? }\n *   DELETE /api/partner/routes/<product>?source=<slug>&value=<value>\n *   GET    /api/partner/routes/<product>/options?source=<slug>\n *   POST   /api/partner/routes/<product>/webhook?source=<slug>[&webhook=<id>]\n *   GET    /api/partner/routes/unrouted?source=<slug>[&product=<slug>]\n *   POST   /api/partner/routes/unrouted/<id>/replay?source=<slug>\n *\n *   → 401 / 3xx  refresh once and retry\n *   → 403 { code: \"SOURCE_ADMIN_REQUIRED\" | \"MFA_REQUIRED\" | \"FORBIDDEN\" }\n *   → 404 { code: \"PRODUCT_NOT_ENTITLED\" | \"TEAM_NOT_FOUND\" | \"ROUTE_NOT_FOUND\"\n *               | \"EVENT_NOT_FOUND\" | \"SOURCE_NOT_FOUND\" }\n *   → 409 { code: \"NO_ROUTING\" | \"NO_WEBHOOK\" }\n *\n * The contract's shapes live here rather than in `@ekanos/integration-schema`,\n * so the routing commands ship with the CLI alone.\n */\n\nconst SourceRefSchema = z.object({\n  id: z.string(),\n  slug: z.string(),\n  name: z.string().nullable(),\n});\n\nconst RouteSchema = z.object({\n  product: z.string(),\n  key: z.string(),\n  value: z.string(),\n  label: z.string().nullable(),\n  team: z.object({\n    id: z.string(),\n    slug: z.string().nullable(),\n    name: z.string(),\n  }),\n  updatedAt: z.string(),\n});\nexport type SourceEventRoute = z.infer<typeof RouteSchema>;\n\nexport const RouteListSchema = z.object({\n  source: SourceRefSchema,\n  routes: z.array(RouteSchema),\n});\n\nexport const RouteSetSchema = z.object({\n  route: RouteSchema,\n  replaced: z.boolean(),\n});\n\nexport const RouteRemoveSchema = z.object({ removed: z.number() });\n\nexport const RouteOptionsSchema = z.object({\n  key: z.string(),\n  options: z\n    .array(z.object({ value: z.string(), label: z.string() }))\n    .nullable(),\n});\n\nexport const RouteWebhookSchema = z.object({\n  webhookId: z.string(),\n  url: z.string(),\n  signature: z\n    .object({ header: z.string(), secretName: z.string() })\n    .nullable(),\n});\n\nconst UnroutedEventSchema = z.object({\n  id: z.string(),\n  product: z.string(),\n  eventId: z.string(),\n  routeKey: z.string().nullable(),\n  routeValue: z.string().nullable(),\n  createdAt: z.string(),\n});\nexport type UnroutedEvent = z.infer<typeof UnroutedEventSchema>;\n\nexport const UnroutedListSchema = z.object({\n  events: z.array(UnroutedEventSchema),\n});\n\nexport const ReplaySchema = z.object({\n  status: z.enum(['routed', 'already-routed', 'unrouted']),\n});\n\nexport type RoutesApiResult<T> =\n  | { status: 'ok'; data: T }\n  | { status: 'unauthorized' };\n\nconst BASE = '/api/partner/routes';\n\nexport async function routesCall<T>(\n  host: string,\n  accessToken: string,\n  schema: z.ZodType<T>,\n  init: {\n    method: 'GET' | 'PUT' | 'POST' | 'DELETE';\n    path?: string;\n    query: Record<string, string | undefined>;\n    body?: unknown;\n  },\n): Promise<RoutesApiResult<T>> {\n  const query = Object.fromEntries(\n    Object.entries(init.query).filter(\n      (entry): entry is [string, string] => entry[1] !== undefined,\n    ),\n  );\n  const url = `${host}${BASE}${init.path ?? ''}?${new URLSearchParams(query)}`;\n  const response = await request(url, {\n    method: init.method,\n    headers: {\n      accept: 'application/json',\n      authorization: `Bearer ${accessToken}`,\n      ...(init.body === undefined\n        ? {}\n        : { 'content-type': 'application/json' }),\n    },\n    body: init.body === undefined ? undefined : JSON.stringify(init.body),\n  });\n\n  if (\n    response.status === 401 ||\n    (response.status >= 300 && response.status < 400)\n  ) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const code = typeof body.code === 'string' ? body.code : null;\n  const message =\n    typeof body.error === 'string' && body.error ? body.error : null;\n\n  if (response.status === 403 && code === 'MFA_REQUIRED') {\n    throw authRequiredError(\n      message ?? `${host} requires multi-factor authentication.`,\n      'Complete MFA in the browser, then run \"ekanos login\" again.',\n    );\n  }\n  if (response.status === 403) {\n    throw forbiddenError(\n      message ?? 'Not permitted on this Source.',\n      code === 'SOURCE_ADMIN_REQUIRED'\n        ? \"Only a Source admin manages the Source's routing. Ask one to run it.\"\n        : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 404) {\n    throw notFoundError(\n      message ?? 'Not found.',\n      code === 'TEAM_NOT_FOUND'\n        ? 'Run \"ekanos teams list\" to see the teams on this Source.'\n        : code === 'ROUTE_NOT_FOUND'\n          ? '\"ekanos routes list\" shows the mapped values.'\n          : code === 'EVENT_NOT_FOUND'\n            ? '\"ekanos routes unrouted\" lists the events waiting for a mapping.'\n            : code === 'PRODUCT_NOT_ENTITLED'\n              ? 'Run \"ekanos catalog\" to see what the Source has.'\n              : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 409) {\n    throw usageError(\n      message ?? 'The integration does not route events.',\n      code === 'NO_WEBHOOK'\n        ? 'Name the webhook: \"ekanos routes webhook <product> --webhook <id>\".'\n        : 'Only an integration that declares a Source connection and a route key routes events.',\n    );\n  }\n  if (response.status === 400) {\n    throw usageError(\n      message ?? 'The host refused the request.',\n      'See \"ekanos routes --help\".',\n    );\n  }\n  if (!response.ok) {\n    throw networkError(\n      `${host}${BASE} responded ${response.status}.`,\n      response.status >= 500\n        ? 'The Ekanos deployment returned a server error. Retry shortly.'\n        : 'Confirm the host runs a build that includes the routes route.',\n    );\n  }\n\n  const parsed = schema.safeParse(body.data);\n  if (!parsed.success) {\n    throw networkError(\n      `${host}${BASE} answered in a shape this CLI does not read.`,\n      'Run \"ekanos upgrade\" — the CLI and the host disagree on the routes contract.',\n    );\n  }\n  return { status: 'ok', data: parsed.data };\n}\n\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n"]}
+{"version":3,"file":"routes-api.js","sourceRoot":"","sources":["../src/routes-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\nimport { request } from './auth/ekanos-api';\nimport {\n  authRequiredError,\n  forbiddenError,\n  invalidStateError,\n  networkError,\n  notFoundError,\n  usageError,\n} from './errors';\n\n/**\n * The CLI's client for a Source's event routing (plan 241.4): which team each\n * value of an integration's route key (Zendesk's organization) belongs to,\n * the Source's webhook endpoint, and the events no team is mapped to yet.\n *\n *   GET    /api/partner/routes?source=<slug>[&product=<slug>]\n *   PUT    /api/partner/routes/<product>?source=<slug>   { value, team, label? }\n *   DELETE /api/partner/routes/<product>?source=<slug>&value=<value>\n *   GET    /api/partner/routes/<product>/options?source=<slug>\n *   POST   /api/partner/routes/<product>/webhook?source=<slug>[&webhook=<id>][&replace=true]\n *   GET    /api/partner/routes/unrouted?source=<slug>[&product=<slug>]\n *   POST   /api/partner/routes/unrouted/<id>/replay?source=<slug>\n *\n *   → 401 / 3xx  refresh once and retry\n *   → 403 { code: \"SOURCE_ADMIN_REQUIRED\" | \"MFA_REQUIRED\" | \"FORBIDDEN\" }\n *   → 404 { code: \"PRODUCT_NOT_ENTITLED\" | \"TEAM_NOT_FOUND\" | \"ROUTE_NOT_FOUND\"\n *               | \"EVENT_NOT_FOUND\" | \"SOURCE_NOT_FOUND\" }\n *   → 409 { code: \"NO_ROUTING\" | \"NO_WEBHOOK\" | \"WEBHOOK_LIVE\" }\n *\n * The contract's shapes live here rather than in `@ekanos/integration-schema`,\n * so the routing commands ship with the CLI alone.\n */\n\nconst SourceRefSchema = z.object({\n  id: z.string(),\n  slug: z.string(),\n  name: z.string().nullable(),\n});\n\nconst RouteSchema = z.object({\n  product: z.string(),\n  key: z.string(),\n  value: z.string(),\n  label: z.string().nullable(),\n  team: z.object({\n    id: z.string(),\n    slug: z.string().nullable(),\n    name: z.string(),\n  }),\n  updatedAt: z.string(),\n});\nexport type SourceEventRoute = z.infer<typeof RouteSchema>;\n\nexport const RouteListSchema = z.object({\n  source: SourceRefSchema,\n  routes: z.array(RouteSchema),\n});\n\nexport const RouteSetSchema = z.object({\n  route: RouteSchema,\n  replaced: z.boolean(),\n});\n\nexport const RouteRemoveSchema = z.object({ removed: z.number() });\n\nexport const RouteOptionsSchema = z.object({\n  key: z.string(),\n  options: z\n    .array(z.object({ value: z.string(), label: z.string() }))\n    .nullable(),\n});\n\nexport const RouteWebhookSchema = z.object({\n  webhookId: z.string(),\n  url: z.string(),\n  signature: z\n    .object({ header: z.string(), secretName: z.string() })\n    .nullable(),\n  /** A live URL was revoked by this mint. An older host does not say. */\n  replaced: z.boolean().optional(),\n});\n\nconst UnroutedEventSchema = z.object({\n  id: z.string(),\n  product: z.string(),\n  eventId: z.string(),\n  routeKey: z.string().nullable(),\n  routeValue: z.string().nullable(),\n  createdAt: z.string(),\n});\nexport type UnroutedEvent = z.infer<typeof UnroutedEventSchema>;\n\nexport const UnroutedListSchema = z.object({\n  events: z.array(UnroutedEventSchema),\n});\n\nexport const ReplaySchema = z.object({\n  status: z.enum(['routed', 'already-routed', 'unrouted']),\n});\n\nexport type RoutesApiResult<T> =\n  | { status: 'ok'; data: T }\n  | { status: 'unauthorized' };\n\nconst BASE = '/api/partner/routes';\n\nexport async function routesCall<T>(\n  host: string,\n  accessToken: string,\n  schema: z.ZodType<T>,\n  init: {\n    method: 'GET' | 'PUT' | 'POST' | 'DELETE';\n    path?: string;\n    query: Record<string, string | undefined>;\n    body?: unknown;\n    /** The hint when the host refuses to replace a live URL unconfirmed. */\n    confirmHint?: string;\n  },\n): Promise<RoutesApiResult<T>> {\n  const query = Object.fromEntries(\n    Object.entries(init.query).filter(\n      (entry): entry is [string, string] => entry[1] !== undefined,\n    ),\n  );\n  const url = `${host}${BASE}${init.path ?? ''}?${new URLSearchParams(query)}`;\n  const response = await request(url, {\n    method: init.method,\n    headers: {\n      accept: 'application/json',\n      authorization: `Bearer ${accessToken}`,\n      ...(init.body === undefined\n        ? {}\n        : { 'content-type': 'application/json' }),\n    },\n    body: init.body === undefined ? undefined : JSON.stringify(init.body),\n  });\n\n  if (\n    response.status === 401 ||\n    (response.status >= 300 && response.status < 400)\n  ) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const code = typeof body.code === 'string' ? body.code : null;\n  const message =\n    typeof body.error === 'string' && body.error ? body.error : null;\n\n  if (response.status === 403 && code === 'MFA_REQUIRED') {\n    throw authRequiredError(\n      message ?? `${host} requires multi-factor authentication.`,\n      'Complete MFA in the browser, then run \"ekanos login\" again.',\n    );\n  }\n  if (response.status === 403) {\n    throw forbiddenError(\n      message ?? 'Not permitted on this Source.',\n      code === 'SOURCE_ADMIN_REQUIRED'\n        ? \"Only a Source admin manages the Source's routing. Ask one to run it.\"\n        : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 404) {\n    throw notFoundError(\n      message ?? 'Not found.',\n      code === 'TEAM_NOT_FOUND'\n        ? 'Run \"ekanos teams list\" to see the teams on this Source.'\n        : code === 'ROUTE_NOT_FOUND'\n          ? '\"ekanos routes list\" shows the mapped values.'\n          : code === 'EVENT_NOT_FOUND'\n            ? '\"ekanos routes unrouted\" lists the events waiting for a mapping.'\n            : code === 'PRODUCT_NOT_ENTITLED'\n              ? 'Run \"ekanos catalog\" to see what the Source has.'\n              : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 409 && code === 'WEBHOOK_LIVE') {\n    throw invalidStateError(\n      message ?? 'The Source already has a live webhook URL.',\n      init.confirmHint ??\n        'Re-run with --yes when you are ready to update the vendor.',\n    );\n  }\n  if (response.status === 409) {\n    throw usageError(\n      message ?? 'The integration does not route events.',\n      code === 'NO_WEBHOOK'\n        ? 'Name the webhook: \"ekanos routes webhook <product> --webhook <id>\".'\n        : 'Only an integration that declares a Source connection and a route key routes events.',\n    );\n  }\n  if (response.status === 400) {\n    throw usageError(\n      message ?? 'The host refused the request.',\n      'See \"ekanos routes --help\".',\n    );\n  }\n  if (!response.ok) {\n    throw networkError(\n      `${host}${BASE} responded ${response.status}.`,\n      response.status >= 500\n        ? 'The Ekanos deployment returned a server error. Retry shortly.'\n        : 'Confirm the host runs a build that includes the routes route.',\n    );\n  }\n\n  const parsed = schema.safeParse(body.data);\n  if (!parsed.success) {\n    throw networkError(\n      `${host}${BASE} answered in a shape this CLI does not read.`,\n      'Run \"ekanos upgrade\" — the CLI and the host disagree on the routes contract.',\n    );\n  }\n  return { status: 'ok', data: parsed.data };\n}\n\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n"]}

package/dist/runs-api.d.ts

@@ -1,4 +1,4 @@
-import { type AgentApprovalDecideRequest, type AgentApprovalDecided, type AgentApprovalList, type AgentRunDetail, type AgentRunList, type AgentRunStartRequest, type AgentRunStarted } from '@ekanos/integration-schema';
+import { type AgentApprovalDecideRequest, type AgentApprovalDecided, type AgentApprovalList, type AgentRunCancelled, type AgentRunDetail, type AgentRunList, type AgentRunStartRequest, type AgentRunStarted } from '@ekanos/integration-schema';
 /**
  * The CLI's client for a team's agent runs and approvals — `ekanos runs`,
  * `ekanos agents test` and `ekanos approvals`.
@@ -6,6 +6,7 @@ import { type AgentApprovalDecideRequest, type AgentApprovalDecided, type AgentA
  *   GET  /api/partner/teams/<team>/runs?source=<slug>[&agent=<key>] → AgentRunList
  *   POST /api/partner/teams/<team>/runs?source=<slug>                → AgentRunStarted
  *   GET  /api/partner/teams/<team>/runs/<id>?source=<slug>[&after=] → AgentRunDetail
+ *   POST /api/partner/teams/<team>/runs/<id>/cancel?source=<slug>    → AgentRunCancelled
  *   GET  /api/partner/teams/<team>/approvals?source=<slug>           → AgentApprovalList
  *   POST /api/partner/teams/<team>/approvals/<id>?source=<slug>      → AgentApprovalDecided
  */
@@ -21,12 +22,17 @@ interface TeamTarget {
 }
 export declare function listRuns(host: string, accessToken: string, target: TeamTarget & {
     agent?: string;
+    status?: string;
+    since?: string;
 }): Promise<RunsApiResult<AgentRunList>>;
 export declare function startRun(host: string, accessToken: string, target: TeamTarget, body: AgentRunStartRequest): Promise<RunsApiResult<AgentRunStarted>>;
 export declare function showRun(host: string, accessToken: string, target: TeamTarget & {
     runId: string;
     after?: number;
 }): Promise<RunsApiResult<AgentRunDetail>>;
+export declare function cancelRun(host: string, accessToken: string, target: TeamTarget & {
+    runId: string;
+}): Promise<RunsApiResult<AgentRunCancelled>>;
 export declare function listApprovals(host: string, accessToken: string, target: TeamTarget): Promise<RunsApiResult<AgentApprovalList>>;
 export declare function decideApproval(host: string, accessToken: string, target: TeamTarget & {
     approvalId: string;

package/dist/runs-api.js

@@ -1,11 +1,11 @@
-import { AgentApprovalDecidedSchema, AgentApprovalListSchema, AgentRunDetailSchema, AgentRunListSchema, AgentRunStartedSchema, } from '@ekanos/integration-schema';
+import { AgentApprovalDecidedSchema, AgentApprovalListSchema, AgentRunCancelledSchema, AgentRunDetailSchema, AgentRunListSchema, AgentRunStartedSchema, } from '@ekanos/integration-schema';
 import { request } from './auth/ekanos-api.js';
 import { authRequiredError, forbiddenError, invalidStateError, networkError, notFoundError, usageError, } from './errors.js';
 export function listRuns(host, accessToken, target) {
     return call(host, accessToken, AgentRunListSchema, {
         method: 'GET',
         path: `${teamPath(target)}/runs`,
-        query: Object.assign({ source: target.source }, (target.agent ? { agent: target.agent } : {})),
+        query: Object.assign(Object.assign(Object.assign({ source: target.source }, (target.agent ? { agent: target.agent } : {})), (target.status ? { status: target.status } : {})), (target.since ? { since: target.since } : {})),
     });
 }
 export function startRun(host, accessToken, target, body) {
@@ -23,6 +23,13 @@ export function showRun(host, accessToken, target) {
         query: Object.assign({ source: target.source }, (target.after ? { after: String(target.after) } : {})),
     });
 }
+export function cancelRun(host, accessToken, target) {
+    return call(host, accessToken, AgentRunCancelledSchema, {
+        method: 'POST',
+        path: `${teamPath(target)}/runs/${encodeURIComponent(target.runId)}/cancel`,
+        query: { source: target.source },
+    });
+}
 export function listApprovals(host, accessToken, target) {
     return call(host, accessToken, AgentApprovalListSchema, {
         method: 'GET',
@@ -62,7 +69,9 @@ async function call(host, accessToken, schema, init) {
     if (response.status === 403) {
         throw forbiddenError(message !== null && message !== void 0 ? message : 'Not permitted on this Source.', code === 'SOURCE_ADMIN_REQUIRED'
             ? "Only a Source admin runs its teams' agents and decides their approvals."
-            : 'Run "ekanos sources" to list the sources you hold a seat on.');
+            : code === 'NOT_A_TEAM_APPROVER'
+                ? "A team's own agent's approvals are the team's: a member who manages its agents decides them, in the app."
+                : 'Run "ekanos sources" to list the sources you hold a seat on.');
     }
     if (response.status === 404) {
         throw notFoundError(message !== null && message !== void 0 ? message : 'Not found.', code === 'TEAM_NOT_FOUND'
@@ -78,9 +87,15 @@ async function call(host, accessToken, schema, init) {
     if (response.status === 409 || response.status === 502) {
         throw invalidStateError(message !== null && message !== void 0 ? message : 'The host refused the request in its current state.', code === 'ALREADY_DECIDED'
             ? 'Run "ekanos approvals list --team <slug>" for what is still waiting.'
-            : code === 'RESUME_FAILED'
-                ? 'The decision is saved; the run picks it up shortly. Check with "ekanos runs show <run-id>".'
-                : 'Check the agent in the app: it may be paused, need a connection, or Agents may be off for this Source.');
+            : code === 'RUN_FINISHED'
+                ? 'Nothing to stop. "ekanos runs show <run-id> --team <slug>" shows how it ended.'
+                : code === 'CANCEL_FAILED'
+                    ? 'Nothing changed. Retry "ekanos runs cancel" shortly.'
+                    : code === 'RESUME_FAILED'
+                        ? 'The decision is saved; the run picks it up shortly. Check with "ekanos runs show <run-id>".'
+                        : code === 'AGENTS_EXPERIENCE_OFF'
+                            ? 'Ask Ekanos to turn on the Agents Experience for this Source: only a super-admin can ("ekanos sources products" shows it as off).'
+                            : 'Run "ekanos teams agents list <team>": the agent may be paused or still need a connection.');
     }
     if (response.status === 400) {
         throw usageError(message !== null && message !== void 0 ? message : 'The host refused the request.', code === 'NOT_EDITABLE'

package/dist/runs-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"runs-api.js","sourceRoot":"","sources":["../src/runs-api.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type AgentApprovalDecideRequest,\n  type AgentApprovalDecided,\n  AgentApprovalDecidedSchema,\n  type AgentApprovalList,\n  AgentApprovalListSchema,\n  type AgentRunDetail,\n  AgentRunDetailSchema,\n  type AgentRunList,\n  AgentRunListSchema,\n  type AgentRunStartRequest,\n  type AgentRunStarted,\n  AgentRunStartedSchema,\n} from '@ekanos/integration-schema';\nimport type { z } from 'zod';\n\nimport { request } from './auth/ekanos-api';\nimport {\n  authRequiredError,\n  forbiddenError,\n  invalidStateError,\n  networkError,\n  notFoundError,\n  usageError,\n} from './errors';\n\n/**\n * The CLI's client for a team's agent runs and approvals — `ekanos runs`,\n * `ekanos agents test` and `ekanos approvals`.\n *\n *   GET  /api/partner/teams/<team>/runs?source=<slug>[&agent=<key>] → AgentRunList\n *   POST /api/partner/teams/<team>/runs?source=<slug>                → AgentRunStarted\n *   GET  /api/partner/teams/<team>/runs/<id>?source=<slug>[&after=] → AgentRunDetail\n *   GET  /api/partner/teams/<team>/approvals?source=<slug>           → AgentApprovalList\n *   POST /api/partner/teams/<team>/approvals/<id>?source=<slug>      → AgentApprovalDecided\n */\n\nexport type RunsApiResult<T> =\n  | { status: 'ok'; data: T }\n  | { status: 'unauthorized' };\n\ninterface TeamTarget {\n  source: string;\n  team: string;\n}\n\nexport function listRuns(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { agent?: string },\n): Promise<RunsApiResult<AgentRunList>> {\n  return call(host, accessToken, AgentRunListSchema, {\n    method: 'GET',\n    path: `${teamPath(target)}/runs`,\n    query: {\n      source: target.source,\n      ...(target.agent ? { agent: target.agent } : {}),\n    },\n  });\n}\n\nexport function startRun(\n  host: string,\n  accessToken: string,\n  target: TeamTarget,\n  body: AgentRunStartRequest,\n): Promise<RunsApiResult<AgentRunStarted>> {\n  return call(host, accessToken, AgentRunStartedSchema, {\n    method: 'POST',\n    path: `${teamPath(target)}/runs`,\n    query: { source: target.source },\n    body,\n  });\n}\n\nexport function showRun(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { runId: string; after?: number },\n): Promise<RunsApiResult<AgentRunDetail>> {\n  return call(host, accessToken, AgentRunDetailSchema, {\n    method: 'GET',\n    path: `${teamPath(target)}/runs/${encodeURIComponent(target.runId)}`,\n    query: {\n      source: target.source,\n      ...(target.after ? { after: String(target.after) } : {}),\n    },\n  });\n}\n\nexport function listApprovals(\n  host: string,\n  accessToken: string,\n  target: TeamTarget,\n): Promise<RunsApiResult<AgentApprovalList>> {\n  return call(host, accessToken, AgentApprovalListSchema, {\n    method: 'GET',\n    path: `${teamPath(target)}/approvals`,\n    query: { source: target.source },\n  });\n}\n\nexport function decideApproval(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { approvalId: string },\n  body: AgentApprovalDecideRequest,\n): Promise<RunsApiResult<AgentApprovalDecided>> {\n  return call(host, accessToken, AgentApprovalDecidedSchema, {\n    method: 'POST',\n    path: `${teamPath(target)}/approvals/${encodeURIComponent(target.approvalId)}`,\n    query: { source: target.source },\n    body,\n  });\n}\n\nfunction teamPath(target: TeamTarget): string {\n  return `/api/partner/teams/${encodeURIComponent(target.team)}`;\n}\n\nasync function call<T>(\n  host: string,\n  accessToken: string,\n  schema: z.ZodType<T>,\n  init: {\n    method: 'GET' | 'POST';\n    path: string;\n    query: Record<string, string>;\n    body?: unknown;\n  },\n): Promise<RunsApiResult<T>> {\n  const response = await request(\n    `${host}${init.path}?${new URLSearchParams(init.query)}`,\n    {\n      method: init.method,\n      headers: {\n        accept: 'application/json',\n        authorization: `Bearer ${accessToken}`,\n        ...(init.body === undefined\n          ? {}\n          : { 'content-type': 'application/json' }),\n      },\n      body: init.body === undefined ? undefined : JSON.stringify(init.body),\n    },\n  );\n\n  if (\n    response.status === 401 ||\n    (response.status >= 300 && response.status < 400)\n  ) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const code = typeof body.code === 'string' ? body.code : null;\n  const message =\n    typeof body.error === 'string' && body.error ? body.error : null;\n\n  if (response.status === 403 && code === 'MFA_REQUIRED') {\n    throw authRequiredError(\n      message ?? `${host} requires multi-factor authentication.`,\n      'Complete MFA in the browser, then run \"ekanos login\" again.',\n    );\n  }\n  if (response.status === 403) {\n    throw forbiddenError(\n      message ?? 'Not permitted on this Source.',\n      code === 'SOURCE_ADMIN_REQUIRED'\n        ? \"Only a Source admin runs its teams' agents and decides their approvals.\"\n        : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 404) {\n    throw notFoundError(\n      message ?? 'Not found.',\n      code === 'TEAM_NOT_FOUND'\n        ? 'Run \"ekanos teams list\" to see the teams on this Source.'\n        : code === 'AGENT_NOT_FOUND' || code === 'TEMPLATE_NOT_FOUND'\n          ? 'Run \"ekanos agents list\" for the Source\\'s agents; a team runs one once it is turned on there.'\n          : code === 'RUN_NOT_FOUND'\n            ? 'Run \"ekanos runs list --team <slug>\" for the team\\'s runs.'\n            : code === 'NOT_FOUND'\n              ? 'Run \"ekanos approvals list --team <slug>\" for what is waiting.'\n              : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 409 || response.status === 502) {\n    throw invalidStateError(\n      message ?? 'The host refused the request in its current state.',\n      code === 'ALREADY_DECIDED'\n        ? 'Run \"ekanos approvals list --team <slug>\" for what is still waiting.'\n        : code === 'RESUME_FAILED'\n          ? 'The decision is saved; the run picks it up shortly. Check with \"ekanos runs show <run-id>\".'\n          : 'Check the agent in the app: it may be paused, need a connection, or Agents may be off for this Source.',\n    );\n  }\n  if (response.status === 400) {\n    throw usageError(\n      message ?? 'The host refused the request.',\n      code === 'NOT_EDITABLE'\n        ? 'Only a reply draft can be edited; approve or reject it instead.'\n        : 'See \"ekanos runs --help\" / \"ekanos approvals --help\".',\n    );\n  }\n  if (!response.ok) {\n    throw networkError(\n      `${host}${init.path} responded ${response.status}.`,\n      response.status >= 500\n        ? 'The Ekanos deployment returned a server error. Retry shortly.'\n        : 'Confirm the host runs a build that includes the runs routes.',\n    );\n  }\n\n  const parsed = schema.safeParse(body.data);\n  if (!parsed.success) {\n    throw networkError(\n      `${host}${init.path} answered in a shape this CLI does not read.`,\n      'Run \"ekanos upgrade\" — the CLI and the host disagree on the runs contract.',\n    );\n  }\n  return { status: 'ok', data: parsed.data };\n}\n\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n"]}
+{"version":3,"file":"runs-api.js","sourceRoot":"","sources":["../src/runs-api.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type AgentApprovalDecideRequest,\n  type AgentApprovalDecided,\n  AgentApprovalDecidedSchema,\n  type AgentApprovalList,\n  AgentApprovalListSchema,\n  type AgentRunCancelled,\n  AgentRunCancelledSchema,\n  type AgentRunDetail,\n  AgentRunDetailSchema,\n  type AgentRunList,\n  AgentRunListSchema,\n  type AgentRunStartRequest,\n  type AgentRunStarted,\n  AgentRunStartedSchema,\n} from '@ekanos/integration-schema';\nimport type { z } from 'zod';\n\nimport { request } from './auth/ekanos-api';\nimport {\n  authRequiredError,\n  forbiddenError,\n  invalidStateError,\n  networkError,\n  notFoundError,\n  usageError,\n} from './errors';\n\n/**\n * The CLI's client for a team's agent runs and approvals — `ekanos runs`,\n * `ekanos agents test` and `ekanos approvals`.\n *\n *   GET  /api/partner/teams/<team>/runs?source=<slug>[&agent=<key>] → AgentRunList\n *   POST /api/partner/teams/<team>/runs?source=<slug>                → AgentRunStarted\n *   GET  /api/partner/teams/<team>/runs/<id>?source=<slug>[&after=] → AgentRunDetail\n *   POST /api/partner/teams/<team>/runs/<id>/cancel?source=<slug>    → AgentRunCancelled\n *   GET  /api/partner/teams/<team>/approvals?source=<slug>           → AgentApprovalList\n *   POST /api/partner/teams/<team>/approvals/<id>?source=<slug>      → AgentApprovalDecided\n */\n\nexport type RunsApiResult<T> =\n  | { status: 'ok'; data: T }\n  | { status: 'unauthorized' };\n\ninterface TeamTarget {\n  source: string;\n  team: string;\n}\n\nexport function listRuns(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { agent?: string; status?: string; since?: string },\n): Promise<RunsApiResult<AgentRunList>> {\n  return call(host, accessToken, AgentRunListSchema, {\n    method: 'GET',\n    path: `${teamPath(target)}/runs`,\n    query: {\n      source: target.source,\n      ...(target.agent ? { agent: target.agent } : {}),\n      ...(target.status ? { status: target.status } : {}),\n      ...(target.since ? { since: target.since } : {}),\n    },\n  });\n}\n\nexport function startRun(\n  host: string,\n  accessToken: string,\n  target: TeamTarget,\n  body: AgentRunStartRequest,\n): Promise<RunsApiResult<AgentRunStarted>> {\n  return call(host, accessToken, AgentRunStartedSchema, {\n    method: 'POST',\n    path: `${teamPath(target)}/runs`,\n    query: { source: target.source },\n    body,\n  });\n}\n\nexport function showRun(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { runId: string; after?: number },\n): Promise<RunsApiResult<AgentRunDetail>> {\n  return call(host, accessToken, AgentRunDetailSchema, {\n    method: 'GET',\n    path: `${teamPath(target)}/runs/${encodeURIComponent(target.runId)}`,\n    query: {\n      source: target.source,\n      ...(target.after ? { after: String(target.after) } : {}),\n    },\n  });\n}\n\nexport function cancelRun(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { runId: string },\n): Promise<RunsApiResult<AgentRunCancelled>> {\n  return call(host, accessToken, AgentRunCancelledSchema, {\n    method: 'POST',\n    path: `${teamPath(target)}/runs/${encodeURIComponent(target.runId)}/cancel`,\n    query: { source: target.source },\n  });\n}\n\nexport function listApprovals(\n  host: string,\n  accessToken: string,\n  target: TeamTarget,\n): Promise<RunsApiResult<AgentApprovalList>> {\n  return call(host, accessToken, AgentApprovalListSchema, {\n    method: 'GET',\n    path: `${teamPath(target)}/approvals`,\n    query: { source: target.source },\n  });\n}\n\nexport function decideApproval(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { approvalId: string },\n  body: AgentApprovalDecideRequest,\n): Promise<RunsApiResult<AgentApprovalDecided>> {\n  return call(host, accessToken, AgentApprovalDecidedSchema, {\n    method: 'POST',\n    path: `${teamPath(target)}/approvals/${encodeURIComponent(target.approvalId)}`,\n    query: { source: target.source },\n    body,\n  });\n}\n\nfunction teamPath(target: TeamTarget): string {\n  return `/api/partner/teams/${encodeURIComponent(target.team)}`;\n}\n\nasync function call<T>(\n  host: string,\n  accessToken: string,\n  schema: z.ZodType<T>,\n  init: {\n    method: 'GET' | 'POST';\n    path: string;\n    query: Record<string, string>;\n    body?: unknown;\n  },\n): Promise<RunsApiResult<T>> {\n  const response = await request(\n    `${host}${init.path}?${new URLSearchParams(init.query)}`,\n    {\n      method: init.method,\n      headers: {\n        accept: 'application/json',\n        authorization: `Bearer ${accessToken}`,\n        ...(init.body === undefined\n          ? {}\n          : { 'content-type': 'application/json' }),\n      },\n      body: init.body === undefined ? undefined : JSON.stringify(init.body),\n    },\n  );\n\n  if (\n    response.status === 401 ||\n    (response.status >= 300 && response.status < 400)\n  ) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const code = typeof body.code === 'string' ? body.code : null;\n  const message =\n    typeof body.error === 'string' && body.error ? body.error : null;\n\n  if (response.status === 403 && code === 'MFA_REQUIRED') {\n    throw authRequiredError(\n      message ?? `${host} requires multi-factor authentication.`,\n      'Complete MFA in the browser, then run \"ekanos login\" again.',\n    );\n  }\n  if (response.status === 403) {\n    throw forbiddenError(\n      message ?? 'Not permitted on this Source.',\n      code === 'SOURCE_ADMIN_REQUIRED'\n        ? \"Only a Source admin runs its teams' agents and decides their approvals.\"\n        : code === 'NOT_A_TEAM_APPROVER'\n          ? \"A team's own agent's approvals are the team's: a member who manages its agents decides them, in the app.\"\n          : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 404) {\n    throw notFoundError(\n      message ?? 'Not found.',\n      code === 'TEAM_NOT_FOUND'\n        ? 'Run \"ekanos teams list\" to see the teams on this Source.'\n        : code === 'AGENT_NOT_FOUND' || code === 'TEMPLATE_NOT_FOUND'\n          ? 'Run \"ekanos agents list\" for the Source\\'s agents; a team runs one once it is turned on there.'\n          : code === 'RUN_NOT_FOUND'\n            ? 'Run \"ekanos runs list --team <slug>\" for the team\\'s runs.'\n            : code === 'NOT_FOUND'\n              ? 'Run \"ekanos approvals list --team <slug>\" for what is waiting.'\n              : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 409 || response.status === 502) {\n    throw invalidStateError(\n      message ?? 'The host refused the request in its current state.',\n      code === 'ALREADY_DECIDED'\n        ? 'Run \"ekanos approvals list --team <slug>\" for what is still waiting.'\n        : code === 'RUN_FINISHED'\n          ? 'Nothing to stop. \"ekanos runs show <run-id> --team <slug>\" shows how it ended.'\n          : code === 'CANCEL_FAILED'\n            ? 'Nothing changed. Retry \"ekanos runs cancel\" shortly.'\n            : code === 'RESUME_FAILED'\n              ? 'The decision is saved; the run picks it up shortly. Check with \"ekanos runs show <run-id>\".'\n              : code === 'AGENTS_EXPERIENCE_OFF'\n                ? 'Ask Ekanos to turn on the Agents Experience for this Source: only a super-admin can (\"ekanos sources products\" shows it as off).'\n                : 'Run \"ekanos teams agents list <team>\": the agent may be paused or still need a connection.',\n    );\n  }\n  if (response.status === 400) {\n    throw usageError(\n      message ?? 'The host refused the request.',\n      code === 'NOT_EDITABLE'\n        ? 'Only a reply draft can be edited; approve or reject it instead.'\n        : 'See \"ekanos runs --help\" / \"ekanos approvals --help\".',\n    );\n  }\n  if (!response.ok) {\n    throw networkError(\n      `${host}${init.path} responded ${response.status}.`,\n      response.status >= 500\n        ? 'The Ekanos deployment returned a server error. Retry shortly.'\n        : 'Confirm the host runs a build that includes the runs routes.',\n    );\n  }\n\n  const parsed = schema.safeParse(body.data);\n  if (!parsed.success) {\n    throw networkError(\n      `${host}${init.path} answered in a shape this CLI does not read.`,\n      'Run \"ekanos upgrade\" — the CLI and the host disagree on the runs contract.',\n    );\n  }\n  return { status: 'ok', data: parsed.data };\n}\n\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n"]}

package/dist/safe-fs.d.ts

@@ -45,6 +45,8 @@ export declare function classifyPath(destPath: string): PathKind;
  * there is no window between deciding and reading.
  */
 export declare function readFileNoFollow(root: string, filePath: string): string | null;
+/** `readFileNoFollow`, as bytes — for comparing a binary file exactly. */
+export declare function readBytesNoFollow(root: string, filePath: string): Buffer | null;
 /**
  * Write a file, creating parent directories, refusing every symlink on the
  * way and at the leaf. `O_NOFOLLOW` on the final open is what makes this safe

package/dist/safe-fs.js

@@ -31,11 +31,11 @@ export function isContained(root, target) {
     return !relative.startsWith('..') && !path.isAbsolute(relative);
 }
 function containmentError(root, target) {
-    throw invalidStateError(`Refusing to write ${target}: it resolves outside the project root ${root}.`, 'Remove the symlink or path component that redirects it, then re-run ' +
-        '"ekanos dev".');
+    throw invalidStateError(`Refusing to write ${target}: it resolves outside ${root}.`, 'Remove the symlink or path component that redirects it, then re-run ' +
+        'the command.');
 }
 function symlinkError(link) {
-    throw invalidStateError(`Refusing to write through the symlink ${link}.`, `"ekanos dev" only writes real files inside your project. Delete ${link} ` +
+    throw invalidStateError(`Refusing to write through the symlink ${link}.`, `The CLI only writes real files inside the folder it writes to. Delete ${link} ` +
         '(or the tree containing it) and re-run.');
 }
 /**
@@ -102,8 +102,8 @@ export function mkdirSafe(root, dir) {
         if (stats.isSymbolicLink())
             symlinkError(current);
         if (!stats.isDirectory()) {
-            throw invalidStateError(`${current} exists and is not a directory, so the harness shell ` +
-                'cannot be written there.', `Move or delete ${current}, then re-run "ekanos dev".`);
+            throw invalidStateError(`${current} exists and is not a directory, so nothing can be ` +
+                'written there.', `Move or delete ${current}, then re-run the command.`);
         }
     }
 }
@@ -131,6 +131,12 @@ export function classifyPath(destPath) {
  * there is no window between deciding and reading.
  */
 export function readFileNoFollow(root, filePath) {
+    var _a;
+    var _b;
+    return (_b = (_a = readBytesNoFollow(root, filePath)) === null || _a === void 0 ? void 0 : _a.toString('utf8')) !== null && _b !== void 0 ? _b : null;
+}
+/** `readFileNoFollow`, as bytes — for comparing a binary file exactly. */
+export function readBytesNoFollow(root, filePath) {
     assertNoSymlinkedComponent(root, filePath);
     let fd;
     try {
@@ -145,7 +151,7 @@ export function readFileNoFollow(root, filePath) {
         throw error;
     }
     try {
-        return fs.readFileSync(fd, 'utf8');
+        return fs.readFileSync(fd);
     }
     finally {
         fs.closeSync(fd);

package/dist/safe-fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe-fs.js","sourceRoot":"","sources":["../src/safe-fs.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { invalidStateError } from './errors';\n\n/**\n * Filesystem primitives for writing into a directory we do not fully trust.\n *\n * `ekanos dev` writes a generated tree into a partner's project, and every\n * path it touches is one an attacker (or a careless `ln -s`) may have created\n * first. Plain `existsSync` + `writeFileSync` follows symlinks, so a\n * `.ekanos/harness` pointing at `~/.ssh`, a generated leaf pointing at a\n * tracked source file, or a DANGLING link (which `existsSync` reports as\n * absent, and which `writeFileSync` then materializes) all let a scaffold\n * write outside the project.\n *\n * Two invariants close that, and both are enforced here rather than at the\n * call sites, because a single unguarded write anywhere reopens the hole:\n *\n *  1. **Containment** — every path resolves inside the project root.\n *  2. **No symlinks** — no component of a path we write through may be a\n *     symlink, and the write itself uses `O_NOFOLLOW` so the kernel enforces\n *     it at open time rather than trusting our earlier `lstat`. That closes\n *     the check→write TOCTOU window: a link swapped in after the check makes\n *     `open` fail with ELOOP instead of following.\n */\n\n/** True when `target` is inside `root` (or is `root` itself). */\nexport function isContained(root: string, target: string): boolean {\n  const relative = path.relative(root, target);\n  if (relative === '') return true;\n  return !relative.startsWith('..') && !path.isAbsolute(relative);\n}\n\nfunction containmentError(root: string, target: string): never {\n  throw invalidStateError(\n    `Refusing to write ${target}: it resolves outside the project root ${root}.`,\n    'Remove the symlink or path component that redirects it, then re-run ' +\n      '\"ekanos dev\".',\n  );\n}\n\nfunction symlinkError(link: string): never {\n  throw invalidStateError(\n    `Refusing to write through the symlink ${link}.`,\n    `\"ekanos dev\" only writes real files inside your project. Delete ${link} ` +\n      '(or the tree containing it) and re-run.',\n  );\n}\n\n/**\n * Walk every path component from `root` down to `target` and refuse if any\n * existing one is a symlink. `lstat` is deliberate — `stat` would resolve the\n * link and report the target's type, which is exactly what we must not do.\n */\nexport function assertNoSymlinkedComponent(root: string, target: string): void {\n  if (!isContained(root, target)) containmentError(root, target);\n\n  const relative = path.relative(root, target);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      // Does not exist yet — nothing to follow, and everything below it is\n      // ours to create.\n      return;\n    }\n    if (stats.isSymbolicLink()) symlinkError(current);\n  }\n}\n\n/**\n * `mkdir -p`, one guarded component at a time. `fs.mkdirSync(recursive)` is\n * happy to walk through a symlinked ancestor; this is not.\n */\nexport function mkdirSafe(root: string, dir: string): void {\n  if (!isContained(root, dir)) containmentError(root, dir);\n\n  const relative = path.relative(root, dir);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats | null = null;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      stats = null;\n    }\n\n    if (stats === null) {\n      try {\n        fs.mkdirSync(current);\n      } catch (error) {\n        const code = (error as NodeJS.ErrnoException).code;\n        // Lost a race to another process; re-check what landed there.\n        if (code !== 'EEXIST') throw error;\n        stats = fs.lstatSync(current);\n      }\n      if (stats === null) continue;\n    }\n\n    if (stats.isSymbolicLink()) symlinkError(current);\n    if (!stats.isDirectory()) {\n      throw invalidStateError(\n        `${current} exists and is not a directory, so the harness shell ` +\n          'cannot be written there.',\n        `Move or delete ${current}, then re-run \"ekanos dev\".`,\n      );\n    }\n  }\n}\n\n/**\n * What `destPath` currently is, without following anything. `'symlink'` is\n * reported for a dangling link too — the case `existsSync` calls absent and\n * `writeFileSync` would silently materialize outside the project.\n */\nexport type PathKind = 'missing' | 'file' | 'directory' | 'symlink' | 'other';\n\nexport function classifyPath(destPath: string): PathKind {\n  let stats: fs.Stats;\n  try {\n    stats = fs.lstatSync(destPath);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';\n    throw error;\n  }\n  if (stats.isSymbolicLink()) return 'symlink';\n  if (stats.isDirectory()) return 'directory';\n  if (stats.isFile()) return 'file';\n  return 'other';\n}\n\n/**\n * Read a file, refusing to follow a symlink at the final component. Returns\n * null when it does not exist. `O_NOFOLLOW` makes the kernel enforce this, so\n * there is no window between deciding and reading.\n */\nexport function readFileNoFollow(\n  root: string,\n  filePath: string,\n): string | null {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(filePath, fs.constants.O_RDONLY | O_NOFOLLOW);\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return null;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    return fs.readFileSync(fd, 'utf8');\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * Write a file, creating parent directories, refusing every symlink on the\n * way and at the leaf. `O_NOFOLLOW` on the final open is what makes this safe\n * against a link swapped in after our checks.\n */\nexport function writeFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string | Uint8Array,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n  mkdirSafe(root, path.dirname(filePath));\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY |\n        fs.constants.O_CREAT |\n        fs.constants.O_TRUNC |\n        O_NOFOLLOW,\n      0o644,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/** Append to an existing file under the same no-follow guarantee. */\nexport function appendFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY | fs.constants.O_APPEND | O_NOFOLLOW,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * `O_NOFOLLOW` is POSIX and present on Linux and macOS. Node exposes it as 0\n * where the platform has no equivalent (Windows), in which case the explicit\n * `lstat` walk above is the whole guarantee rather than a belt to the kernel's\n * braces.\n */\nconst O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;\n"]}
+{"version":3,"file":"safe-fs.js","sourceRoot":"","sources":["../src/safe-fs.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { invalidStateError } from './errors';\n\n/**\n * Filesystem primitives for writing into a directory we do not fully trust.\n *\n * `ekanos dev` writes a generated tree into a partner's project, and every\n * path it touches is one an attacker (or a careless `ln -s`) may have created\n * first. Plain `existsSync` + `writeFileSync` follows symlinks, so a\n * `.ekanos/harness` pointing at `~/.ssh`, a generated leaf pointing at a\n * tracked source file, or a DANGLING link (which `existsSync` reports as\n * absent, and which `writeFileSync` then materializes) all let a scaffold\n * write outside the project.\n *\n * Two invariants close that, and both are enforced here rather than at the\n * call sites, because a single unguarded write anywhere reopens the hole:\n *\n *  1. **Containment** — every path resolves inside the project root.\n *  2. **No symlinks** — no component of a path we write through may be a\n *     symlink, and the write itself uses `O_NOFOLLOW` so the kernel enforces\n *     it at open time rather than trusting our earlier `lstat`. That closes\n *     the check→write TOCTOU window: a link swapped in after the check makes\n *     `open` fail with ELOOP instead of following.\n */\n\n/** True when `target` is inside `root` (or is `root` itself). */\nexport function isContained(root: string, target: string): boolean {\n  const relative = path.relative(root, target);\n  if (relative === '') return true;\n  return !relative.startsWith('..') && !path.isAbsolute(relative);\n}\n\nfunction containmentError(root: string, target: string): never {\n  throw invalidStateError(\n    `Refusing to write ${target}: it resolves outside ${root}.`,\n    'Remove the symlink or path component that redirects it, then re-run ' +\n      'the command.',\n  );\n}\n\nfunction symlinkError(link: string): never {\n  throw invalidStateError(\n    `Refusing to write through the symlink ${link}.`,\n    `The CLI only writes real files inside the folder it writes to. Delete ${link} ` +\n      '(or the tree containing it) and re-run.',\n  );\n}\n\n/**\n * Walk every path component from `root` down to `target` and refuse if any\n * existing one is a symlink. `lstat` is deliberate — `stat` would resolve the\n * link and report the target's type, which is exactly what we must not do.\n */\nexport function assertNoSymlinkedComponent(root: string, target: string): void {\n  if (!isContained(root, target)) containmentError(root, target);\n\n  const relative = path.relative(root, target);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      // Does not exist yet — nothing to follow, and everything below it is\n      // ours to create.\n      return;\n    }\n    if (stats.isSymbolicLink()) symlinkError(current);\n  }\n}\n\n/**\n * `mkdir -p`, one guarded component at a time. `fs.mkdirSync(recursive)` is\n * happy to walk through a symlinked ancestor; this is not.\n */\nexport function mkdirSafe(root: string, dir: string): void {\n  if (!isContained(root, dir)) containmentError(root, dir);\n\n  const relative = path.relative(root, dir);\n  if (relative === '') return;\n\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    let stats: fs.Stats | null = null;\n    try {\n      stats = fs.lstatSync(current);\n    } catch {\n      stats = null;\n    }\n\n    if (stats === null) {\n      try {\n        fs.mkdirSync(current);\n      } catch (error) {\n        const code = (error as NodeJS.ErrnoException).code;\n        // Lost a race to another process; re-check what landed there.\n        if (code !== 'EEXIST') throw error;\n        stats = fs.lstatSync(current);\n      }\n      if (stats === null) continue;\n    }\n\n    if (stats.isSymbolicLink()) symlinkError(current);\n    if (!stats.isDirectory()) {\n      throw invalidStateError(\n        `${current} exists and is not a directory, so nothing can be ` +\n          'written there.',\n        `Move or delete ${current}, then re-run the command.`,\n      );\n    }\n  }\n}\n\n/**\n * What `destPath` currently is, without following anything. `'symlink'` is\n * reported for a dangling link too — the case `existsSync` calls absent and\n * `writeFileSync` would silently materialize outside the project.\n */\nexport type PathKind = 'missing' | 'file' | 'directory' | 'symlink' | 'other';\n\nexport function classifyPath(destPath: string): PathKind {\n  let stats: fs.Stats;\n  try {\n    stats = fs.lstatSync(destPath);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';\n    throw error;\n  }\n  if (stats.isSymbolicLink()) return 'symlink';\n  if (stats.isDirectory()) return 'directory';\n  if (stats.isFile()) return 'file';\n  return 'other';\n}\n\n/**\n * Read a file, refusing to follow a symlink at the final component. Returns\n * null when it does not exist. `O_NOFOLLOW` makes the kernel enforce this, so\n * there is no window between deciding and reading.\n */\nexport function readFileNoFollow(\n  root: string,\n  filePath: string,\n): string | null {\n  return readBytesNoFollow(root, filePath)?.toString('utf8') ?? null;\n}\n\n/** `readFileNoFollow`, as bytes — for comparing a binary file exactly. */\nexport function readBytesNoFollow(\n  root: string,\n  filePath: string,\n): Buffer | null {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(filePath, fs.constants.O_RDONLY | O_NOFOLLOW);\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return null;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    return fs.readFileSync(fd);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * Write a file, creating parent directories, refusing every symlink on the\n * way and at the leaf. `O_NOFOLLOW` on the final open is what makes this safe\n * against a link swapped in after our checks.\n */\nexport function writeFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string | Uint8Array,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n  mkdirSafe(root, path.dirname(filePath));\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY |\n        fs.constants.O_CREAT |\n        fs.constants.O_TRUNC |\n        O_NOFOLLOW,\n      0o644,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/** Append to an existing file under the same no-follow guarantee. */\nexport function appendFileNoFollow(\n  root: string,\n  filePath: string,\n  contents: string,\n): void {\n  assertNoSymlinkedComponent(root, filePath);\n\n  let fd: number;\n  try {\n    fd = fs.openSync(\n      filePath,\n      fs.constants.O_WRONLY | fs.constants.O_APPEND | O_NOFOLLOW,\n    );\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === 'ELOOP') symlinkError(filePath);\n    throw error;\n  }\n\n  try {\n    fs.writeFileSync(fd, contents);\n  } finally {\n    fs.closeSync(fd);\n  }\n}\n\n/**\n * `O_NOFOLLOW` is POSIX and present on Linux and macOS. Node exposes it as 0\n * where the platform has no equivalent (Windows), in which case the explicit\n * `lstat` walk above is the whole guarantee rather than a belt to the kernel's\n * braces.\n */\nconst O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;\n"]}

package/dist/secret-file.d.ts

@@ -0,0 +1,17 @@
+export declare const SECRETS_DIRNAME = "secrets";
+/** Create (or tighten) `~/.ekanos/secrets` and return it; refuse if unusable. */
+export declare function ensureSecretsDir(env: Record<string, string | undefined>): string;
+export interface SecretFileInput {
+    /** The team (or, for a Source-wide secret, the Source) it belongs to. */
+    owner: string;
+    /** What it is, for the file name: `zendesk-webhook`, `triage-new-ticket-trigger`. */
+    what: string;
+    /** A line saying what the secret is for and where it goes. */
+    purpose: string;
+    /** `NAME=value` pairs, in order. */
+    values: Array<[name: string, value: string]>;
+    /** The command to run for a fresh one, should this file not be written. */
+    again: string;
+}
+/** Write the secret to a new 0600 file in `dir` and return its path. */
+export declare function writeSecretFile(dir: string, input: SecretFileInput, now?: Date): string;

package/dist/secret-file.js

@@ -0,0 +1,69 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveEkanosHome } from './auth/credential-store.js';
+import { preconditionError } from './errors.js';
+/**
+ * Where a secret the host shows once goes instead of the terminal: a new
+ * file under `~/.ekanos/secrets/`, readable only by you. A command's output
+ * — a person's terminal, and just as often a coding agent's context — names
+ * the file and what it is for, never the value. The same in a TTY and not,
+ * in human output and `--json` (which carries `secretFile`).
+ *
+ * The directory is 0700 and each file 0600, created exclusively (never
+ * overwriting, never through an existing path), the same discipline as the
+ * credentials file beside it. A command makes sure the directory is usable
+ * BEFORE it asks the host for the secret, so a secret is never minted (and
+ * an old one revoked) with nowhere to put it.
+ */
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+export const SECRETS_DIRNAME = 'secrets';
+/** Create (or tighten) `~/.ekanos/secrets` and return it; refuse if unusable. */
+export function ensureSecretsDir(env) {
+    const dir = path.join(resolveEkanosHome(env), '.ekanos', SECRETS_DIRNAME);
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+        fs.chmodSync(dir, DIR_MODE);
+        fs.accessSync(dir, fs.constants.W_OK);
+    }
+    catch (error) {
+        throw preconditionError(`${dir} is not usable for secrets: ${error instanceof Error ? error.message : String(error)}.`, 'Make it writable (or set EKANOS_HOME), then run the command again. Nothing was changed.');
+    }
+    return dir;
+}
+/** Write the secret to a new 0600 file in `dir` and return its path. */
+export function writeSecretFile(dir, input, now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:]/g, '').replace('.', '');
+    const base = `${part(input.owner)}-${part(input.what)}-${stamp}`;
+    const content = [
+        `# ${input.purpose}`,
+        `# Written by the ekanos CLI at ${now.toISOString()}. It is shown nowhere else.`,
+        '# Copy it from here yourself (not into a chat or an agent session), then delete this file.',
+        ...input.values.map(([name, value]) => `${name}=${value}`),
+        '',
+    ].join('\n');
+    let lastError = null;
+    for (let attempt = 1; attempt <= 20; attempt += 1) {
+        const file = path.join(dir, attempt === 1 ? base : `${base}-${attempt}`);
+        try {
+            fs.writeFileSync(file, content, { mode: FILE_MODE, flag: 'wx' });
+            fs.chmodSync(file, FILE_MODE);
+            return file;
+        }
+        catch (error) {
+            lastError = error;
+            if (error.code !== 'EEXIST')
+                break;
+        }
+    }
+    throw preconditionError(`The new secret could not be saved in ${dir}: ${lastError instanceof Error ? lastError.message : String(lastError)}. It was not shown.`, `Fix the directory, then make a fresh one: ${input.again}`);
+}
+/** A file-name-safe piece: lowercase letters, digits, dots and dashes. */
+function part(value) {
+    return (value
+        .toLowerCase()
+        .replace(/[^a-z0-9.-]+/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '')
+        .slice(0, 60) || 'secret');
+}
+//# sourceMappingURL=secret-file.js.map

package/dist/secret-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-file.js","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { resolveEkanosHome } from './auth/credential-store';\nimport { preconditionError } from './errors';\n\n/**\n * Where a secret the host shows once goes instead of the terminal: a new\n * file under `~/.ekanos/secrets/`, readable only by you. A command's output\n * — a person's terminal, and just as often a coding agent's context — names\n * the file and what it is for, never the value. The same in a TTY and not,\n * in human output and `--json` (which carries `secretFile`).\n *\n * The directory is 0700 and each file 0600, created exclusively (never\n * overwriting, never through an existing path), the same discipline as the\n * credentials file beside it. A command makes sure the directory is usable\n * BEFORE it asks the host for the secret, so a secret is never minted (and\n * an old one revoked) with nowhere to put it.\n */\n\nconst DIR_MODE = 0o700;\nconst FILE_MODE = 0o600;\n\nexport const SECRETS_DIRNAME = 'secrets';\n\n/** Create (or tighten) `~/.ekanos/secrets` and return it; refuse if unusable. */\nexport function ensureSecretsDir(\n  env: Record<string, string | undefined>,\n): string {\n  const dir = path.join(resolveEkanosHome(env), '.ekanos', SECRETS_DIRNAME);\n  try {\n    fs.mkdirSync(dir, { recursive: true, mode: DIR_MODE });\n    fs.chmodSync(dir, DIR_MODE);\n    fs.accessSync(dir, fs.constants.W_OK);\n  } catch (error) {\n    throw preconditionError(\n      `${dir} is not usable for secrets: ${error instanceof Error ? error.message : String(error)}.`,\n      'Make it writable (or set EKANOS_HOME), then run the command again. Nothing was changed.',\n    );\n  }\n  return dir;\n}\n\nexport interface SecretFileInput {\n  /** The team (or, for a Source-wide secret, the Source) it belongs to. */\n  owner: string;\n  /** What it is, for the file name: `zendesk-webhook`, `triage-new-ticket-trigger`. */\n  what: string;\n  /** A line saying what the secret is for and where it goes. */\n  purpose: string;\n  /** `NAME=value` pairs, in order. */\n  values: Array<[name: string, value: string]>;\n  /** The command to run for a fresh one, should this file not be written. */\n  again: string;\n}\n\n/** Write the secret to a new 0600 file in `dir` and return its path. */\nexport function writeSecretFile(\n  dir: string,\n  input: SecretFileInput,\n  now: Date = new Date(),\n): string {\n  const stamp = now.toISOString().replace(/[-:]/g, '').replace('.', '');\n  const base = `${part(input.owner)}-${part(input.what)}-${stamp}`;\n  const content = [\n    `# ${input.purpose}`,\n    `# Written by the ekanos CLI at ${now.toISOString()}. It is shown nowhere else.`,\n    '# Copy it from here yourself (not into a chat or an agent session), then delete this file.',\n    ...input.values.map(([name, value]) => `${name}=${value}`),\n    '',\n  ].join('\\n');\n\n  let lastError: unknown = null;\n  for (let attempt = 1; attempt <= 20; attempt += 1) {\n    const file = path.join(dir, attempt === 1 ? base : `${base}-${attempt}`);\n    try {\n      fs.writeFileSync(file, content, { mode: FILE_MODE, flag: 'wx' });\n      fs.chmodSync(file, FILE_MODE);\n      return file;\n    } catch (error) {\n      lastError = error;\n      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') break;\n    }\n  }\n  throw preconditionError(\n    `The new secret could not be saved in ${dir}: ${lastError instanceof Error ? lastError.message : String(lastError)}. It was not shown.`,\n    `Fix the directory, then make a fresh one: ${input.again}`,\n  );\n}\n\n/** A file-name-safe piece: lowercase letters, digits, dots and dashes. */\nfunction part(value: string): string {\n  return (\n    value\n      .toLowerCase()\n      .replace(/[^a-z0-9.-]+/g, '-')\n      .replace(/^[-.]+|[-.]+$/g, '')\n      .slice(0, 60) || 'secret'\n  );\n}\n"]}

package/dist/skills-api.d.ts

@@ -1,4 +1,4 @@
-import { type SourceSkillList, type SourceSkillPushRequest, type SourceSkillPushResult, type SourceSkillShow } from '@ekanos/integration-schema';
+import { type SourceSkillArchiveResult, type SourceSkillList, type SourceSkillPushRequest, type SourceSkillPushResult, type SourceSkillShow } from '@ekanos/integration-schema';
 /**
  * The CLI's client for a Source's skills.
  *
@@ -9,12 +9,15 @@ import { type SourceSkillList, type SourceSkillPushRequest, type SourceSkillPush
  *   GET  /api/partner/skills?source=<s>[&team=<t>]           → { ok, data: SourceSkillList }
  *   GET  /api/partner/skills/<slug>?source=<s>[&team=<t>]    → { ok, data: SourceSkillShow }
  *   POST /api/partner/skills     SourceSkillPushRequest      → { ok, data: SourceSkillPushResult }
+ *   POST /api/partner/skills/<slug>/archive | unarchive  { source, team? }
+ *                                                           → { ok, data: SourceSkillArchiveResult }
  *
  *   → 401 / 3xx                        refresh once and retry
  *   → 400 { code: "INVALID_SKILL", issues: { path, message }[] }
  *   → 403 { code: "MFA_REQUIRED" | "FORBIDDEN" | "SOURCE_ADMIN_REQUIRED" }
  *   → 404 { code: "SOURCE_NOT_FOUND" | "TEAM_NOT_FOUND" | "SKILL_NOT_FOUND" }
- *   → 409 { code: "SKILL_NOT_PROMPT" }
+ *   → 409 { code: "SKILL_NOT_PROMPT" | "SKILL_ARCHIVED" }
+ *   → 409 { code: "SKILL_IN_USE", inUse: SourceSkillInUse }   archive
  * ---------------------------------------------------------------------------
  */
 export type SkillsApiResult<T> = {
@@ -26,3 +29,8 @@ export type SkillsApiResult<T> = {
 export declare function listSkills(host: string, accessToken: string, source: string, team?: string): Promise<SkillsApiResult<SourceSkillList>>;
 export declare function showSkill(host: string, accessToken: string, source: string, slug: string, team?: string): Promise<SkillsApiResult<SourceSkillShow>>;
 export declare function pushSkill(host: string, accessToken: string, body: SourceSkillPushRequest): Promise<SkillsApiResult<SourceSkillPushResult>>;
+export declare function archiveSkill(host: string, accessToken: string, action: 'archive' | 'unarchive', params: {
+    source: string;
+    slug: string;
+    team?: string;
+}): Promise<SkillsApiResult<SourceSkillArchiveResult>>;

package/dist/skills-api.js

@@ -1,4 +1,4 @@
-import { SourceSkillListSchema, SourceSkillPushResultSchema, SourceSkillShowSchema, } from '@ekanos/integration-schema';
+import { SourceSkillArchiveResultSchema, SourceSkillInUseSchema, SourceSkillListSchema, SourceSkillPushResultSchema, SourceSkillShowSchema, } from '@ekanos/integration-schema';
 import { request } from './auth/ekanos-api.js';
 import { authRequiredError, forbiddenError, invalidStateError, networkError, notFoundError, usageError, validationError, } from './errors.js';
 const ROUTE = '/api/partner/skills';
@@ -27,6 +27,15 @@ export function pushSkill(host, accessToken, body) {
         subject: body.slug,
     });
 }
+export function archiveSkill(host, accessToken, action, params) {
+    return call(host, accessToken, SourceSkillArchiveResultSchema, {
+        method: 'POST',
+        path: `${ROUTE}/${encodeURIComponent(params.slug)}/${action}`,
+        body: Object.assign({ source: params.source }, (params.team ? { team: params.team } : {})),
+        subject: params.slug,
+        source: params.source,
+    });
+}
 async function call(host, accessToken, schema, init) {
     const response = await request(`${host}${init.path}`, {
         method: init.method,
@@ -63,7 +72,7 @@ async function call(host, accessToken, schema, init) {
     }
     if (response.status === 403) {
         throw forbiddenError(message !== null && message !== void 0 ? message : 'Not permitted on this Source.', code === 'SOURCE_ADMIN_REQUIRED'
-            ? 'Only a Source admin pushes skills or reads team skills. Ask one to run it.'
+            ? 'Only a Source admin pushes or archives skills, or reads team skills. Ask one to run it.'
             : 'Run "ekanos sources" to list the sources you hold a seat on.');
     }
     if (response.status === 404) {
@@ -73,6 +82,12 @@ async function call(host, accessToken, schema, init) {
                 ? 'Run "ekanos teams list" to see the Source\'s teams.'
                 : 'Run "ekanos skills list" to see the skills.');
     }
+    if (response.status === 409 && code === 'SKILL_ARCHIVED') {
+        throw invalidStateError(message !== null && message !== void 0 ? message : `"${init.subject}" is archived.`, `Run "ekanos skills unarchive ${init.subject}" first, or push it under another slug.`);
+    }
+    if (response.status === 409 && code === 'SKILL_IN_USE') {
+        throw skillInUseError(message !== null && message !== void 0 ? message : `"${init.subject}" is still in use.`, body.inUse, init.subject, init.source);
+    }
     if (response.status === 409) {
         throw invalidStateError(message !== null && message !== void 0 ? message : `"${init.subject}" cannot be pushed.`, 'Rename the skill folder (its slug) and push again.');
     }
@@ -87,6 +102,26 @@ async function call(host, accessToken, schema, init) {
     }
     return { status: 'ok', data: parsed.data };
 }
+/** What still uses the skill, and the command that stops each use. */
+function skillInUseError(message, value, slug, source) {
+    const parsed = SourceSkillInUseSchema.safeParse(value);
+    const inUse = parsed.success ? parsed.data : { templates: [], agents: [] };
+    const on = source ? ` --source ${source}` : '';
+    return invalidStateError([
+        message,
+        ...inUse.templates.map((template) => `  agent ${template.key} (${template.name}) names it`),
+        ...inUse.agents.map((agent) => `  ${agent.team}: agent ${agent.agent} has it attached` +
+            (agent.fromTemplate
+                ? ' (from an older template version it is pinned to)'
+                : '')),
+    ].join('\n'), [
+        'Stop each use, then archive again:',
+        ...inUse.templates.map((template) => `  ekanos agents pull ${template.key}${on}, drop "${slug}" from its skills, then agents apply and agents publish (or archive the agent: ekanos agents archive ${template.key}${on})`),
+        ...inUse.agents.map((agent) => agent.fromTemplate
+            ? `  ekanos teams agents unpin ${agent.team} ${agent.agent}${on}`
+            : `  ekanos teams agents skills ${agent.team} ${agent.agent} remove ${slug}${on}`),
+    ].join('\n'));
+}
 async function readOptionalJson(response) {
     try {
         const parsed = await response.json();