@lunnoa/client 1.2.0 → 1.4.0

package/README.md

@@ -113,6 +113,8 @@ Most namespaces map to the Public API surface (`openapi.public.json`):
 
 `approvals` uses the authenticated **workspace** API (`/api/approvals/...`), not Public API v1. The inbox is filtered to requests where the current user is an eligible approver.
 
+`scorecards` also uses the workspace API (`/api/scorecards/...`): `list`, `get`, and `recordValue(measureId, { value, period?, note? })` to push a measure value from your own system (API key needs `scorecard:record`).
+
 Errors are `LunnoaApiError` with `status`, `body`, and convenience flags (`isUnauthorized`, `isForbidden`, `isRateLimited`). Paginated lists have async iteration (`entities.iterate(...)`, `queueItems.iterate(...)`).
 
 ## Worked examples
@@ -266,7 +268,7 @@ Re-run codegen whenever entity types, workflows, or agents change on the deploym
 
 ## Define, run, and CLI deploy
 
-Author local definitions with `defineWorkflow` / `defineAgent` / `defineEntityType`, run linear chains with `lunnoa.runs.start`, and upsert with the CLI (prefer CLI over calling upsert from app code). Entity types are workspace-scoped (no `--project-id`); instance writes reject unknown attribute keys unless `allowUnknownAttributes` is true — use the reserved `extensions` object for flexible bags:
+Author local definitions with `defineWorkflow` / `defineAgent` / `defineEntityType`, run linear chains with `lunnoa.runs.start`, and upsert with the CLI (prefer CLI over calling upsert from app code). An entity type slug is unique on the deployment. Deploy grants that type to the API key's workspace when the slug is new, and will not rewrite a type already granted to other workspaces (no `--project-id`). Instance writes reject unknown attribute keys unless `allowUnknownAttributes` is true — use the reserved `extensions` object for flexible bags:
 
 ```bash
 npx @lunnoa/client entity-types deploy ./human.ts --url https://lunnoa.example --api-key lna_...
@@ -320,7 +322,9 @@ Two Cursor / Claude Code skills ship in the published package under `skills/`:
 | **lunnoa-solution-design** | [`skills/lunnoa-solution-design/SKILL.md`](./skills/lunnoa-solution-design/SKILL.md) | Interview the human, map intent to Lunnoa primitives, produce a build brief |
 | **lunnoa-client** | [`skills/lunnoa-client/SKILL.md`](./skills/lunnoa-client/SKILL.md) | Implement with auth, discovery, codegen, `define*` / `runs` / CLI deploy, React hooks |
 
-After install, copy or enable them from `node_modules/@lunnoa/client/skills/` into your app’s `.cursor/skills/` (or Claude Code skills directory). Prefer **solution-design** first when requirements are unclear, then **lunnoa-client**.
+Install them into your app with `npx @lunnoa/client skills install`. It copies the skills of the installed SDK version into `.claude/skills/` and `.cursor/skills/`. Add it as a `postinstall` script and gitignore both folders so the skills stay in step with the SDK. Prefer **solution-design** first when requirements are unclear, then **lunnoa-client**.
+
+In this repo, edit `skills/` only; `pnpm install` copies it into the local `.cursor/skills/` and `.claude/skills/`.
 
 Partner paste block:
 

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli/index.ts
 import { mkdir, writeFile } from "fs/promises";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 
 // src/core/auth.ts
 var API_KEY_PREFIX = "lna_";
@@ -430,10 +430,7 @@ var AgentChatClient = class {
         raw: true,
         signal: options.signal,
         headers: { Accept: "text/event-stream" },
-        body: {
-          messages: [uiMessage],
-          ...options.chatMode ? { chatMode: options.chatMode } : {}
-        }
+        body: messageTaskBody(uiMessage, options)
       }
     );
     return new AgentChatStream(response, { signal: options.signal });
@@ -472,6 +469,14 @@ var AgentChatClient = class {
     );
   }
 };
+function messageTaskBody(message, options = {}) {
+  return {
+    messages: [message],
+    ...options.chatMode ? { chatMode: options.chatMode } : {},
+    ...options.data ? { data: options.data } : {},
+    ...options.piiResolution ? { piiResolution: options.piiResolution } : {}
+  };
+}
 function generateMessageId() {
   const cryptoObj = globalThis.crypto;
   if (cryptoObj?.randomUUID) {
@@ -1005,7 +1010,6 @@ var EntitiesResource = class {
       objectTypeSlug: options.objectTypeSlug,
       state: options.state,
       states: options.states?.join(","),
-      ownerId: options.ownerId,
       search: options.search,
       sortBy: options.sortBy,
       sortOrder: options.sortOrder,
@@ -1038,7 +1042,7 @@ var EntityTypesResource = class {
   }
   http;
   /**
-   * Lists entity types in the workspace. Request
+   * Lists entity types granted to the API key's workspace. Request
    * `expansion: ['attributeSchema', 'stateSchema']` for the field and state
    * machine definitions the codegen CLI builds types from.
    */
@@ -1063,7 +1067,9 @@ var EntityTypesResource = class {
     });
   }
   /**
-   * Creates or updates an entity type by workspace-scoped slug.
+   * Creates or updates an entity type by deployment-wide slug.
+   * A new slug is granted to the API key's workspace. A slug already shared
+   * with another workspace is rejected unless the key belongs to a platform admin.
    * Prefer the CLI (`npx @lunnoa/client entity-types deploy`) for happy-path deploy.
    */
   upsertBySlug(definition) {
@@ -1416,7 +1422,7 @@ function computeDurationMs(start, end) {
   return b - a;
 }
 function defaultSleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 
 // src/resources/knowledge.ts
@@ -1601,10 +1607,11 @@ var QueueItemsResource = class {
   listRetryable(queueId) {
     return this.http.get(`/api/queues/${queueId}/items/retry`);
   }
-  /** Returns items with the given status. */
-  listByStatus(queueId, status) {
+  /** Returns a page of items with the given status. */
+  listByStatus(queueId, status, options = {}) {
     return this.http.get(
-      `/api/queues/${queueId}/items/status/${status}`
+      `/api/queues/${queueId}/items/status/${status}`,
+      { query: { limit: options.limit, offset: options.offset } }
     );
   }
   /** Looks an item up by the external ID your system supplied. */
@@ -1613,11 +1620,22 @@ var QueueItemsResource = class {
       `/api/queues/${queueId}/items/external/${externalId}`
     );
   }
-  /** Searches items in the queue. */
-  search(queueId, query) {
-    return this.http.get(`/api/queues/${queueId}/items/search`, {
-      query: { q: query }
-    });
+  /**
+   * Searches items by external id, item data, and metadata.
+   * Returns one page, same shape as `list`.
+   */
+  search(queueId, query, options = {}) {
+    return this.http.get(
+      `/api/queues/${queueId}/items/search`,
+      {
+        query: {
+          limit: options.limit,
+          offset: options.offset,
+          expansion: serializeCsv(options.expansion),
+          filterBy: serializeFilterBy({ search: query })
+        }
+      }
+    );
   }
   /** Returns per-status and per-priority counts for the queue. */
   stats(queueId) {
@@ -1653,10 +1671,21 @@ var QueueItemsResource = class {
   addError(queueId, itemId, error) {
     return this.http.post(
       `/api/queues/${queueId}/items/${itemId}/error`,
-      { body: error }
+      {
+        body: {
+          error: error.error,
+          errorDetails: serializeErrorDetails(error.errorDetails)
+        }
+      }
     );
   }
 };
+function serializeErrorDetails(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
 
 // src/resources/queues.ts
 var QueuesResource = class {
@@ -1783,6 +1812,32 @@ var RunsResource = class {
   }
 };
 
+// src/resources/scorecards.ts
+var ScorecardsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists scorecards in the workspace. */
+  list() {
+    return this.http.get("/api/scorecards");
+  }
+  /** Returns a scorecard with objectives, measures, latest values and status. */
+  get(scorecardId) {
+    return this.http.get(`/api/scorecards/${scorecardId}`);
+  }
+  /**
+   * Records a measure value. A value for the same period replaces the current
+   * one; the old value is kept as superseded history.
+   */
+  recordValue(measureId, data) {
+    return this.http.post(
+      `/api/scorecards/measures/${measureId}/values`,
+      { body: data }
+    );
+  }
+};
+
 // src/resources/tasks.ts
 var TasksResource = class {
   constructor(http) {
@@ -1833,12 +1888,7 @@ var TasksResource = class {
     } : message;
     return this.http.post(
       `/api/agents/${agentId}/tasks/${taskId}/message`,
-      {
-        body: {
-          messages: [uiMessage],
-          ...options.chatMode ? { chatMode: options.chatMode } : {}
-        }
-      }
+      { body: messageTaskBody(uiMessage, options) }
     );
   }
 };
@@ -2021,6 +2071,7 @@ var LunnoaClient = class {
   queues;
   queueItems;
   variables;
+  scorecards;
   connections;
   projects;
   workflowApps;
@@ -2043,6 +2094,7 @@ var LunnoaClient = class {
     this.queues = new QueuesResource(this.http);
     this.queueItems = new QueueItemsResource(this.http);
     this.variables = new VariablesResource(this.http);
+    this.scorecards = new ScorecardsResource(this.http);
     this.connections = new ConnectionsResource(this.http);
     this.projects = new ProjectsResource(this.http);
     this.discovery = new DiscoveryResource(this.http);
@@ -2057,7 +2109,8 @@ var GROUPS_WITH_SUBCOMMAND = /* @__PURE__ */ new Set([
   "tools",
   "apps",
   "connections",
-  "projects"
+  "projects",
+  "skills"
 ]);
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--url",
@@ -2164,6 +2217,9 @@ var USAGE = `Usage:
   npx @lunnoa/client agents deploy <path> --url <url> --api-key <key> --project-id <uuid>
   npx @lunnoa/client entity-types deploy <path> --url <url> --api-key <key>
 
+  Agent skills (copies this version's skills into .claude/skills and .cursor/skills):
+  npx @lunnoa/client skills install [projectDir]
+
 Options:
   --url           Base URL of the Lunnoa Automate deployment
   --api-key       Machine API key (lna_...)
@@ -2179,8 +2235,9 @@ Environment: LUNNOA_URL, LUNNOA_API_KEY, LUNNOA_PROJECT_ID
 Optional config file: lunnoa.config.ts | .mjs | .js | .json
 
 tools get prints inputConfig and a defineAction() sketch. tools list is compact;
-run tools get for the schema. Entity-type deploy is workspace-scoped (no
---project-id). Unknown instance attributes are rejected unless
+run tools get for the schema. Entity-type deploy uses a deployment-wide slug
+and grants the API key's workspace when the slug is new (no --project-id).
+A slug already granted to other workspaces is not rewritten. Unknown instance attributes are rejected unless
 allowUnknownAttributes is true; use extensions.
 `;
 
@@ -2831,7 +2888,7 @@ function generateDeploymentModule(definitions) {
  *
  * Schema fingerprint: ${schemaFingerprint}
  */
-import type { LunnoaClient, Entity, Execution, ExecuteWorkflowResult, PaginatedEntities, Task, AgentChatStream, WaitUntilFinishedOptions, ListEntitiesOptions, UIMessage } from '@lunnoa/client';
+import type { LunnoaClient, Entity, Execution, ExecuteWorkflowResult, PaginatedEntities, Task, AgentChatStream, WaitUntilFinishedOptions, ListEntitiesOptions, StreamMessageOptions, UIMessage } from '@lunnoa/client';
 
 /** Fingerprint of entity-type schemas at codegen time (slug:revision:allowUnknown). */
 export const DEPLOYMENT_SCHEMA_FINGERPRINT = ${JSON.stringify(schemaFingerprint)};
@@ -3019,7 +3076,7 @@ function typedEntityAccessor<A, S extends string>(
       })) as Typed;
     },
     /** Creates an entity of this type with compile-time checked attributes. */
-    async create(data: { name: string; attributes?: A; state?: S; ownerId?: string }): Promise<Typed> {
+    async create(data: { name: string; attributes?: A; state?: S }): Promise<Typed> {
       return (await client.entities.create(
         { ...data, objectTypeId } as never,
         { expansion: ['attributes'] },
@@ -3028,7 +3085,7 @@ function typedEntityAccessor<A, S extends string>(
     /** Partially updates an entity of this type. */
     async update(
       entityId: string,
-      data: { name?: string; attributes?: Partial<A>; ownerId?: string },
+      data: { name?: string; attributes?: Partial<A> },
     ): Promise<Typed> {
       return (await client.entities.update(entityId, data as never, {
         expansion: ['attributes'],
@@ -3074,13 +3131,17 @@ function typedAgentAccessor(client: LunnoaClient, agentId: string) {
     streamMessage(
       taskId: string,
       message: string | UIMessage,
-      options?: { chatMode?: 'builder' | 'preview'; signal?: AbortSignal },
+      options?: StreamMessageOptions,
     ): Promise<AgentChatStream> {
       return client.agentChat.streamMessage(agentId, taskId, message, options);
     },
     /** Sends a message and waits for the full turn (non-streaming). */
-    message(taskId: string, message: string | UIMessage) {
-      return client.tasks.message(agentId, taskId, message);
+    message(
+      taskId: string,
+      message: string | UIMessage,
+      options?: Omit<StreamMessageOptions, 'signal'>,
+    ) {
+      return client.tasks.message(agentId, taskId, message, options);
     },
   };
 }
@@ -3176,6 +3237,26 @@ async function loadOptionalConfig() {
   return {};
 }
 
+// src/cli/skills.ts
+import { cp } from "fs/promises";
+import { dirname, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+var SKILL_TARGETS = [".claude/skills", ".cursor/skills"];
+var BUNDLED_SKILLS_DIR = resolve2(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "skills"
+);
+async function installSkills(projectDir, sourceDir = BUNDLED_SKILLS_DIR) {
+  const written = [];
+  for (const target of SKILL_TARGETS) {
+    const dest = resolve2(projectDir, target);
+    await cp(sourceDir, dest, { recursive: true, force: true });
+    written.push(dest);
+  }
+  return written;
+}
+
 // src/cli/index.ts
 async function bindClient(args) {
   const fileConfig = await loadOptionalConfig();
@@ -3231,9 +3312,9 @@ async function runCodegen(args) {
     `Found ${definitions.entityTypes.length} entity type(s), ${definitions.workflows.length} workflow(s), ${definitions.agents.length} agent(s).`
   );
   const moduleSource = generateDeploymentModule(definitions);
-  const outDir = resolve2(process.cwd(), args.out);
+  const outDir = resolve3(process.cwd(), args.out);
   await mkdir(outDir, { recursive: true });
-  const outFile = resolve2(outDir, "lunnoa.generated.ts");
+  const outFile = resolve3(outDir, "lunnoa.generated.ts");
   await writeFile(outFile, moduleSource, "utf8");
   console.log(`Wrote ${outFile}`);
 }
@@ -3405,6 +3486,13 @@ async function main() {
     console.log(USAGE);
     return;
   }
+  if (args.command === "skills" && args.subcommand === "install") {
+    const written = await installSkills(resolve3(process.cwd(), args.path ?? "."));
+    for (const dest of written) {
+      console.log(`Installed Lunnoa skills into ${dest}`);
+    }
+    return;
+  }
   if (args.command === "codegen") {
     await runCodegen(args);
     return;

package/dist/index.cjs

@@ -426,10 +426,7 @@ var AgentChatClient = class {
         raw: true,
         signal: options.signal,
         headers: { Accept: "text/event-stream" },
-        body: {
-          messages: [uiMessage],
-          ...options.chatMode ? { chatMode: options.chatMode } : {}
-        }
+        body: messageTaskBody(uiMessage, options)
       }
     );
     return new AgentChatStream(response, { signal: options.signal });
@@ -468,6 +465,14 @@ var AgentChatClient = class {
     );
   }
 };
+function messageTaskBody(message, options = {}) {
+  return {
+    messages: [message],
+    ...options.chatMode ? { chatMode: options.chatMode } : {},
+    ...options.data ? { data: options.data } : {},
+    ...options.piiResolution ? { piiResolution: options.piiResolution } : {}
+  };
+}
 function generateMessageId() {
   const cryptoObj = globalThis.crypto;
   if (cryptoObj?.randomUUID) {
@@ -1047,7 +1052,6 @@ var EntitiesResource = class {
       objectTypeSlug: options.objectTypeSlug,
       state: options.state,
       states: options.states?.join(","),
-      ownerId: options.ownerId,
       search: options.search,
       sortBy: options.sortBy,
       sortOrder: options.sortOrder,
@@ -1080,7 +1084,7 @@ var EntityTypesResource = class {
   }
   http;
   /**
-   * Lists entity types in the workspace. Request
+   * Lists entity types granted to the API key's workspace. Request
    * `expansion: ['attributeSchema', 'stateSchema']` for the field and state
    * machine definitions the codegen CLI builds types from.
    */
@@ -1105,7 +1109,9 @@ var EntityTypesResource = class {
     });
   }
   /**
-   * Creates or updates an entity type by workspace-scoped slug.
+   * Creates or updates an entity type by deployment-wide slug.
+   * A new slug is granted to the API key's workspace. A slug already shared
+   * with another workspace is rejected unless the key belongs to a platform admin.
    * Prefer the CLI (`npx @lunnoa/client entity-types deploy`) for happy-path deploy.
    */
   upsertBySlug(definition) {
@@ -1643,10 +1649,11 @@ var QueueItemsResource = class {
   listRetryable(queueId) {
     return this.http.get(`/api/queues/${queueId}/items/retry`);
   }
-  /** Returns items with the given status. */
-  listByStatus(queueId, status) {
+  /** Returns a page of items with the given status. */
+  listByStatus(queueId, status, options = {}) {
     return this.http.get(
-      `/api/queues/${queueId}/items/status/${status}`
+      `/api/queues/${queueId}/items/status/${status}`,
+      { query: { limit: options.limit, offset: options.offset } }
     );
   }
   /** Looks an item up by the external ID your system supplied. */
@@ -1655,11 +1662,22 @@ var QueueItemsResource = class {
       `/api/queues/${queueId}/items/external/${externalId}`
     );
   }
-  /** Searches items in the queue. */
-  search(queueId, query) {
-    return this.http.get(`/api/queues/${queueId}/items/search`, {
-      query: { q: query }
-    });
+  /**
+   * Searches items by external id, item data, and metadata.
+   * Returns one page, same shape as `list`.
+   */
+  search(queueId, query, options = {}) {
+    return this.http.get(
+      `/api/queues/${queueId}/items/search`,
+      {
+        query: {
+          limit: options.limit,
+          offset: options.offset,
+          expansion: serializeCsv(options.expansion),
+          filterBy: serializeFilterBy({ search: query })
+        }
+      }
+    );
   }
   /** Returns per-status and per-priority counts for the queue. */
   stats(queueId) {
@@ -1695,10 +1713,21 @@ var QueueItemsResource = class {
   addError(queueId, itemId, error) {
     return this.http.post(
       `/api/queues/${queueId}/items/${itemId}/error`,
-      { body: error }
+      {
+        body: {
+          error: error.error,
+          errorDetails: serializeErrorDetails(error.errorDetails)
+        }
+      }
     );
   }
 };
+function serializeErrorDetails(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
 
 // src/resources/queues.ts
 var QueuesResource = class {
@@ -1825,6 +1854,32 @@ var RunsResource = class {
   }
 };
 
+// src/resources/scorecards.ts
+var ScorecardsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists scorecards in the workspace. */
+  list() {
+    return this.http.get("/api/scorecards");
+  }
+  /** Returns a scorecard with objectives, measures, latest values and status. */
+  get(scorecardId) {
+    return this.http.get(`/api/scorecards/${scorecardId}`);
+  }
+  /**
+   * Records a measure value. A value for the same period replaces the current
+   * one; the old value is kept as superseded history.
+   */
+  recordValue(measureId, data) {
+    return this.http.post(
+      `/api/scorecards/measures/${measureId}/values`,
+      { body: data }
+    );
+  }
+};
+
 // src/resources/tasks.ts
 var TasksResource = class {
   constructor(http) {
@@ -1875,12 +1930,7 @@ var TasksResource = class {
     } : message;
     return this.http.post(
       `/api/agents/${agentId}/tasks/${taskId}/message`,
-      {
-        body: {
-          messages: [uiMessage],
-          ...options.chatMode ? { chatMode: options.chatMode } : {}
-        }
-      }
+      { body: messageTaskBody(uiMessage, options) }
     );
   }
 };
@@ -2063,6 +2113,7 @@ var LunnoaClient = class {
   queues;
   queueItems;
   variables;
+  scorecards;
   connections;
   projects;
   workflowApps;
@@ -2085,6 +2136,7 @@ var LunnoaClient = class {
     this.queues = new QueuesResource(this.http);
     this.queueItems = new QueueItemsResource(this.http);
     this.variables = new VariablesResource(this.http);
+    this.scorecards = new ScorecardsResource(this.http);
     this.connections = new ConnectionsResource(this.http);
     this.projects = new ProjectsResource(this.http);
     this.discovery = new DiscoveryResource(this.http);
@@ -2186,6 +2238,7 @@ exports.ProjectsResource = ProjectsResource;
 exports.QueueItemsResource = QueueItemsResource;
 exports.QueuesResource = QueuesResource;
 exports.RunsResource = RunsResource;
+exports.ScorecardsResource = ScorecardsResource;
 exports.SsoAuthResource = SsoAuthResource;
 exports.TasksResource = TasksResource;
 exports.VariablesResource = VariablesResource;