@lunnoa/client 0.0.0-development

package/dist/cli.js

@@ -0,0 +1,2635 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { mkdir, writeFile } from "fs/promises";
+import { resolve as resolve2 } from "path";
+
+// src/core/auth.ts
+var API_KEY_PREFIX = "lna_";
+function isBrowserEnvironment() {
+  return typeof window !== "undefined";
+}
+function assertApiKeyAllowedInEnvironment(apiKey) {
+  if (isBrowserEnvironment()) {
+    throw new Error(
+      "Refusing to use a Lunnoa API key (lna_...) in a browser environment. API keys are server-side credentials: anyone opening dev tools could read the key and act as the service account across its whole workspace. Either call the Lunnoa API from your own backend which holds the key (backend-for-frontend pattern), or authenticate the end user with a Lunnoa user JWT and pass it as `accessToken`."
+    );
+  }
+  if (!apiKey.startsWith(API_KEY_PREFIX)) {
+    throw new Error(
+      `Invalid Lunnoa API key: expected it to start with "${API_KEY_PREFIX}". If you are passing a user JWT, use the \`accessToken\` option instead of \`apiKey\`.`
+    );
+  }
+}
+
+// src/core/errors.ts
+var LunnoaApiError = class extends Error {
+  /** HTTP status code of the failed response. */
+  status;
+  /** Parsed JSON error body when the server returned one, otherwise the raw text. */
+  body;
+  /** HTTP method of the failed request. */
+  method;
+  /** Path of the failed request (without the base URL). */
+  path;
+  constructor(args) {
+    const detail = extractMessage(args.body);
+    super(
+      `Lunnoa API request failed: ${args.method} ${args.path} \u2192 ${args.status}${detail ? ` (${detail})` : ""}`
+    );
+    this.name = "LunnoaApiError";
+    this.status = args.status;
+    this.body = args.body;
+    this.method = args.method;
+    this.path = args.path;
+  }
+  /** True for 401 responses (missing, revoked, or expired credential). */
+  get isUnauthorized() {
+    return this.status === 401;
+  }
+  /** True for 403 responses (missing permission or feature not licensed). */
+  get isForbidden() {
+    return this.status === 403;
+  }
+  /** True for 404 responses. */
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** True for 429 responses (rate limited). */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+function extractMessage(body) {
+  if (body && typeof body === "object") {
+    const record = body;
+    const candidate = record.message ?? record.error;
+    if (typeof candidate === "string") {
+      return candidate;
+    }
+    if (Array.isArray(candidate)) {
+      return candidate.filter((m) => typeof m === "string").join("; ");
+    }
+  }
+  if (typeof body === "string" && body.length > 0 && body.length < 300) {
+    return body;
+  }
+  return void 0;
+}
+
+// src/core/http.ts
+var HttpClient = class {
+  baseUrl;
+  tokenStore;
+  /** Underlying fetch (shared with AI SDK transports when needed). */
+  fetch;
+  apiKey;
+  accessToken;
+  autoRefresh;
+  defaultHeaders;
+  refreshInFlight = null;
+  constructor(options) {
+    if (!options.baseUrl) {
+      throw new Error("LunnoaClient requires a baseUrl.");
+    }
+    if (!options.apiKey && !options.accessToken && !options.tokenStore) {
+      throw new Error(
+        "LunnoaClient requires an apiKey (server-side), an accessToken (user JWT), or a tokenStore (Pattern B)."
+      );
+    }
+    if (options.apiKey) {
+      assertApiKeyAllowedInEnvironment(options.apiKey);
+    }
+    if (typeof options.accessToken === "string" && options.accessToken.startsWith(API_KEY_PREFIX)) {
+      throw new Error(
+        "The accessToken option received an lna_ API key. API keys must be passed as `apiKey` (and never in a browser); accessToken is for user JWTs only."
+      );
+    }
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.accessToken = options.accessToken;
+    this.tokenStore = options.tokenStore;
+    this.autoRefresh = options.autoRefresh ?? Boolean(options.tokenStore && !options.apiKey);
+    this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.defaultHeaders = options.headers ?? {};
+  }
+  async resolveAuthHeader() {
+    if (this.apiKey) {
+      return `Bearer ${this.apiKey}`;
+    }
+    if (this.tokenStore) {
+      const fromStore = await this.tokenStore.getAccessToken();
+      if (!fromStore) {
+        throw new Error(
+          "No access token in the token store. Call lunnoa.auth.login(...) first, or seed the store with setTokens / createMemoryTokenStore({ accessToken })."
+        );
+      }
+      return `Bearer ${fromStore}`;
+    }
+    const token = typeof this.accessToken === "function" ? await this.accessToken() : this.accessToken;
+    if (!token) {
+      throw new Error("accessToken resolved to an empty value.");
+    }
+    return `Bearer ${token}`;
+  }
+  buildUrl(path, query) {
+    const url = new URL(this.baseUrl + path);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  async request(method, path, options = {}) {
+    const url = this.buildUrl(path, options.query);
+    const headers = {
+      ...this.defaultHeaders,
+      ...options.headers
+    };
+    if (!options.skipAuth) {
+      headers.Authorization = await this.resolveAuthHeader();
+    }
+    const init = { method, headers, signal: options.signal };
+    if (options.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(options.body);
+    }
+    const response = await this.fetch(url, init);
+    if (!response.ok && response.status === 401 && !options.skipAuth && !options._retriedAfterRefresh && this.autoRefresh && this.tokenStore && !this.apiKey) {
+      const refreshed = await this.tryRefreshAccessToken();
+      if (refreshed) {
+        return this.request(method, path, {
+          ...options,
+          _retriedAfterRefresh: true
+        });
+      }
+    }
+    if (!response.ok) {
+      const body = await parseBodySafely(response);
+      throw new LunnoaApiError({
+        status: response.status,
+        body,
+        method,
+        path
+      });
+    }
+    if (options.raw) {
+      return response;
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    return await parseBodySafely(response);
+  }
+  get(path, options) {
+    return this.request("GET", path, options);
+  }
+  post(path, options) {
+    return this.request("POST", path, options);
+  }
+  patch(path, options) {
+    return this.request("PATCH", path, options);
+  }
+  put(path, options) {
+    return this.request("PUT", path, options);
+  }
+  delete(path, options) {
+    return this.request("DELETE", path, options);
+  }
+  /**
+   * Single-flight refresh using the token store. Returns false when refresh
+   * is impossible or fails (store is cleared on failure).
+   */
+  async tryRefreshAccessToken() {
+    if (!this.tokenStore) {
+      return false;
+    }
+    if (!this.refreshInFlight) {
+      this.refreshInFlight = this.performRefresh().finally(() => {
+        this.refreshInFlight = null;
+      });
+    }
+    return this.refreshInFlight;
+  }
+  async performRefresh() {
+    const refreshToken = await this.tokenStore.getRefreshToken();
+    if (!refreshToken) {
+      return false;
+    }
+    try {
+      const url = this.buildUrl("/api/auth/refresh-token");
+      const response = await this.fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refreshToken })
+      });
+      if (!response.ok) {
+        await this.tokenStore.clear();
+        return false;
+      }
+      const body = await parseBodySafely(response);
+      if (!body?.access_token) {
+        await this.tokenStore.clear();
+        return false;
+      }
+      await this.tokenStore.setTokens({ accessToken: body.access_token });
+      return true;
+    } catch {
+      await this.tokenStore.clear();
+      return false;
+    }
+  }
+};
+async function parseBodySafely(response) {
+  const text = await response.text();
+  if (!text) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+// src/streaming/sse.ts
+async function* parseSseStream(stream) {
+  for await (const event of parseSseEvents(stream)) {
+    if (event.data !== null) {
+      yield event.data;
+    }
+  }
+}
+async function* parseSseEvents(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      buffer = buffer.replace(/\r\n/g, "\n");
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        const rawEvent = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        boundary = buffer.indexOf("\n\n");
+        const parsed = extractEvent(rawEvent);
+        if (parsed.data !== null || parsed.event !== "message") {
+          yield parsed;
+        }
+      }
+    }
+    const remaining = buffer.trim();
+    if (remaining) {
+      const parsed = extractEvent(remaining);
+      if (parsed.data !== null || parsed.event !== "message") {
+        yield parsed;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function extractEvent(rawEvent) {
+  const dataLines = [];
+  let eventName = "message";
+  for (const line of rawEvent.split("\n")) {
+    if (line.startsWith(":")) {
+      continue;
+    }
+    if (line.startsWith("event:")) {
+      let value = line.slice("event:".length);
+      if (value.startsWith(" ")) {
+        value = value.slice(1);
+      }
+      if (value) {
+        eventName = value;
+      }
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      let value = line.slice("data:".length);
+      if (value.startsWith(" ")) {
+        value = value.slice(1);
+      }
+      dataLines.push(value);
+    }
+  }
+  return {
+    event: eventName,
+    data: dataLines.length === 0 ? null : dataLines.join("\n")
+  };
+}
+
+// src/streaming/agent-chat.ts
+var AgentChatStream = class {
+  constructor(response, options) {
+    this.response = response;
+    this.options = options;
+    this.runId = response.headers.get("X-Task-Run-Id");
+  }
+  response;
+  options;
+  /**
+   * Server run id of this turn (`X-Task-Run-Id` response header), when
+   * provided. Useful for diagnostics.
+   */
+  runId;
+  consumed = false;
+  [Symbol.asyncIterator]() {
+    return this.chunks();
+  }
+  async *chunks() {
+    if (this.consumed) {
+      throw new Error("This AgentChatStream has already been consumed.");
+    }
+    this.consumed = true;
+    const body = this.response.body;
+    if (!body) {
+      return;
+    }
+    for await (const data of parseSseStream(body)) {
+      if (this.options?.signal?.aborted) {
+        return;
+      }
+      if (data === "[DONE]") {
+        return;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      if (parsed && typeof parsed === "object" && "type" in parsed) {
+        yield parsed;
+      }
+    }
+  }
+  /**
+   * The same chunks as a web `ReadableStream`, ready for the AI SDK's
+   * `readUIMessageStream({ stream })` to assemble into `UIMessage` snapshots.
+   */
+  toUIMessageStream() {
+    const iterator = this.chunks();
+    return new ReadableStream({
+      async pull(controller) {
+        const { done, value } = await iterator.next();
+        if (done) {
+          controller.close();
+        } else {
+          controller.enqueue(value);
+        }
+      },
+      async cancel() {
+        await iterator.return();
+      }
+    });
+  }
+  /** Collects the full text of the turn (concatenated `text-delta` chunks). */
+  async text() {
+    let text = "";
+    for await (const chunk of this.chunks()) {
+      if (chunk.type === "text-delta" && typeof chunk.delta === "string") {
+        text += chunk.delta;
+      }
+    }
+    return text;
+  }
+};
+var AgentChatClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Sends a user message to an agent task and streams the assistant turn.
+   * Creates the task row when `taskId` does not exist yet (client-generated
+   * UUIDs are supported, mirroring the bundled UI).
+   *
+   * `message` may be a plain string (wrapped into a UIMessage) or a full AI
+   * SDK `UIMessage`.
+   */
+  async streamMessage(agentId, taskId, message, options = {}) {
+    const uiMessage = typeof message === "string" ? {
+      id: generateMessageId(),
+      role: "user",
+      parts: [{ type: "text", text: message }]
+    } : message;
+    const response = await this.http.request(
+      "POST",
+      `/api/agents/${agentId}/tasks/${taskId}/stream-message`,
+      {
+        raw: true,
+        signal: options.signal,
+        headers: { Accept: "text/event-stream" },
+        body: {
+          messages: [uiMessage],
+          ...options.chatMode ? { chatMode: options.chatMode } : {}
+        }
+      }
+    );
+    return new AgentChatStream(response, { signal: options.signal });
+  }
+  /**
+   * Reattaches to an in-flight agent turn after a disconnect (the resumable
+   * stream replays from the beginning of the turn). Returns `null` when
+   * there is no active stream to resume (server responds 204).
+   */
+  async resumeStream(agentId, taskId, options = {}) {
+    const response = await this.http.request(
+      "GET",
+      `/api/agents/${agentId}/tasks/${taskId}/stream-message`,
+      {
+        raw: true,
+        signal: options.signal,
+        headers: { Accept: "text/event-stream" }
+      }
+    );
+    if (response.status === 204) {
+      return null;
+    }
+    return new AgentChatStream(response, { signal: options.signal });
+  }
+  /**
+   * Requests cancellation of the active agent turn for a task. Idempotent:
+   * succeeds even when no stream is active. Optionally persists the partial
+   * assistant message received so far.
+   */
+  async stop(agentId, taskId, options = {}) {
+    return this.http.post(
+      `/api/agents/${agentId}/tasks/${taskId}/stream-message/stop`,
+      {
+        body: options.assistantMessage ? { assistantMessage: options.assistantMessage } : {}
+      }
+    );
+  }
+};
+function generateMessageId() {
+  const cryptoObj = globalThis.crypto;
+  if (cryptoObj?.randomUUID) {
+    return cryptoObj.randomUUID();
+  }
+  return `msg_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// src/resources/actions.ts
+var ActionsResource = class {
+  constructor(http, executions) {
+    this.http = http;
+    this.executions = executions;
+  }
+  http;
+  executions;
+  /**
+   * Run a single catalogue action as a one-step ad-hoc Execution (`source: SDK`).
+   *
+   * The platform runs the action synchronously and returns the execution id
+   * plus status/output/executionPath. You can also poll
+   * {@link ExecutionsResource.get} / {@link ExecutionsResource.waitUntilFinished}
+   * with the returned id.
+   *
+   * Discover `appId` / `actionId` / `inputConfig` via `workflowApps.list()`.
+   */
+  run(options) {
+    return this.http.post("/api/actions/run", {
+      body: options
+    });
+  }
+  /**
+   * Convenience: run the action and wait until the Execution reaches a
+   * terminal status (or pauses in `NEEDS_INPUT`). Prefer {@link run} when the
+   * synchronous response is enough.
+   */
+  async runAndWait(options, waitOptions) {
+    const { id } = await this.run(options);
+    return this.executions.waitUntilFinished(id, {
+      ...waitOptions,
+      expansion: [
+        "executionPath",
+        "source",
+        ...waitOptions?.expansion ?? []
+      ]
+    });
+  }
+  /**
+   * Thin discovery helper: find one action definition from `workflowApps.list()`.
+   * Prefer calling `workflowApps.list()` once and caching when looking up many
+   * actions.
+   */
+  async get(appId, actionId) {
+    const apps = await this.http.get("/api/workflow-apps");
+    const app = apps.find((a) => a.id === appId);
+    return app?.actions?.find((action) => action.id === actionId);
+  }
+};
+
+// src/define/index.ts
+var DEFINE_KINDS = {
+  connection: "connection",
+  aiConnection: "aiConnection",
+  action: "action",
+  workflow: "workflow",
+  agent: "agent"
+};
+function resolveActionAppId(action) {
+  if (action.appId?.trim()) {
+    return action.appId.trim();
+  }
+  const id = action.id.trim();
+  const actionMarker = "_action_";
+  const markerIndex = id.indexOf(actionMarker);
+  if (markerIndex > 0) {
+    return id.slice(0, markerIndex);
+  }
+  const dot = id.indexOf(".");
+  if (dot > 0) {
+    return id.slice(0, dot);
+  }
+  throw new Error(
+    `Cannot infer appId for action "${id}". Pass appId explicitly.`
+  );
+}
+function resolveActionId(action) {
+  const id = action.id.trim();
+  const appId = action.appId?.trim();
+  if (appId && id.startsWith(`${appId}.`)) {
+    return id.slice(appId.length + 1);
+  }
+  const marker = "_action_";
+  if (id.includes(marker)) {
+    return id;
+  }
+  const dot = id.indexOf(".");
+  if (dot > 0) {
+    return id.slice(dot + 1);
+  }
+  return id;
+}
+
+// src/resources/common.ts
+function serializeListQuery(options = {}) {
+  return {
+    expansion: serializeCsv(options.expansion),
+    filterBy: serializeFilterBy(options.filterBy),
+    includeType: serializeCsv(options.includeType)
+  };
+}
+function serializeCsv(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return Array.isArray(value) ? value.join(",") : value;
+}
+function serializeFilterBy(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return Object.entries(value).map(([key, filterValue]) => `${key}:${filterValue}`).join(",");
+}
+
+// src/resources/agents.ts
+function unwrapTool(tool) {
+  if ("use" in tool && tool.use) {
+    return tool.use;
+  }
+  return tool;
+}
+function agentDefinitionToUpsert(def, options) {
+  const tools = [];
+  const workflowIds = [...options?.workflowIds ?? []];
+  for (const tool of def.tools ?? []) {
+    const unwrapped = unwrapTool(tool);
+    if (unwrapped.kind === DEFINE_KINDS.workflow) {
+      continue;
+    }
+    if (unwrapped.kind === DEFINE_KINDS.action) {
+      tools.push({
+        appId: resolveActionAppId(unwrapped),
+        actionId: resolveActionId(unwrapped),
+        connectionId: unwrapped.connection?.id,
+        name: unwrapped.name,
+        description: unwrapped.description,
+        input: unwrapped.input
+      });
+    }
+  }
+  return {
+    slug: def.slug,
+    name: def.name,
+    description: def.description,
+    instructions: def.instructions,
+    model: def.model,
+    aiConnectionId: def.aiConnection?.id,
+    connectionIds: def.connections?.map((c) => c.id).filter((id) => Boolean(id)),
+    workflowIds: workflowIds.length ? workflowIds : void 0,
+    tools,
+    managedByCode: true
+  };
+}
+var AgentsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists agents visible to the caller in the current workspace. */
+  list(options) {
+    return this.http.get("/api/agents", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single agent. */
+  get(agentId, options) {
+    return this.http.get(`/api/agents/${agentId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Upsert an agent by project-scoped slug.
+   * Prefer the CLI (`npx @lunnoa/client agents deploy`) for happy-path deploy.
+   */
+  upsertBySlug(projectId, body, options) {
+    const payload = "kind" in body && body.kind === "agent" ? agentDefinitionToUpsert(body, options) : body;
+    return this.http.post(`/api/projects/${projectId}/agents/upsert`, {
+      body: payload
+    });
+  }
+};
+
+// src/auth/types.ts
+function isLoginRequires2FA(result) {
+  return "requires2FA" in result && result.requires2FA === true;
+}
+function mapWireTokens(wire) {
+  return {
+    accessToken: wire.access_token,
+    ...wire.refresh_token !== void 0 ? { refreshToken: wire.refresh_token } : {}
+  };
+}
+function mapLoginWire(wire) {
+  if ("requires2FA" in wire && wire.requires2FA) {
+    return {
+      requires2FA: true,
+      sessionToken: wire.sessionToken
+    };
+  }
+  const tokens = wire;
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token
+  };
+}
+
+// src/resources/auth.ts
+var AuthResource = class {
+  constructor(http, tokenStore) {
+    this.http = http;
+    this.tokenStore = tokenStore;
+    this.sso = new SsoAuthResource(http);
+  }
+  http;
+  tokenStore;
+  sso;
+  /**
+   * `POST /api/auth/login`
+   *
+   * On success without 2FA, tokens are written to the token store (when set).
+   * When 2FA is required, returns `{ requires2FA, sessionToken }` and does not
+   * store tokens until {@link verify2faLogin} succeeds.
+   */
+  async login(input) {
+    const wire = await this.http.post("/api/auth/login", {
+      body: { email: input.email, password: input.password },
+      skipAuth: true
+    });
+    const result = mapLoginWire(wire);
+    if (!isLoginRequires2FA(result)) {
+      await this.persistTokens(result);
+    }
+    return result;
+  }
+  /**
+   * `POST /api/auth/2fa/verify-login`
+   *
+   * Completes password login after TOTP or backup-code verification.
+   */
+  async verify2faLogin(input) {
+    const wire = await this.http.post(
+      "/api/auth/2fa/verify-login",
+      {
+        body: {
+          sessionToken: input.sessionToken,
+          token: input.token
+        },
+        skipAuth: true
+      }
+    );
+    const result = mapLoginWire(wire);
+    if (isLoginRequires2FA(result)) {
+      throw new Error(
+        "Unexpected 2FA challenge after verify2faLogin; expected access and refresh tokens."
+      );
+    }
+    await this.persistTokens(result);
+    return result;
+  }
+  /**
+   * `POST /api/auth/login-with-token`
+   *
+   * Exchanges a short-lived hidden JWT (SSO callback or email verification)
+   * for access and refresh tokens.
+   */
+  async loginWithToken(input) {
+    const wire = await this.http.post("/api/auth/login-with-token", {
+      body: { token: input.token },
+      skipAuth: true
+    });
+    const tokens = {
+      accessToken: wire.access_token,
+      refreshToken: wire.refresh_token
+    };
+    await this.persistTokens(tokens);
+    return tokens;
+  }
+  /**
+   * `POST /api/auth/refresh-token`
+   *
+   * Returns a new access token. The refresh token itself is not rotated.
+   * When a token store is configured and `refreshToken` is omitted, the
+   * stored refresh token is used.
+   */
+  async refresh(input) {
+    const refreshToken = input?.refreshToken ?? await this.tokenStore?.getRefreshToken() ?? null;
+    if (!refreshToken) {
+      throw new Error(
+        "auth.refresh requires a refreshToken argument or a token store that holds one."
+      );
+    }
+    const wire = await this.http.post(
+      "/api/auth/refresh-token",
+      {
+        body: { refreshToken },
+        skipAuth: true
+      }
+    );
+    const mapped = mapWireTokens(wire);
+    if (this.tokenStore) {
+      await this.tokenStore.setTokens({
+        accessToken: mapped.accessToken,
+        // Keep existing refresh token; refresh responses omit it.
+        refreshToken: mapped.refreshToken
+      });
+    }
+    return { accessToken: mapped.accessToken };
+  }
+  /**
+   * `GET /api/users/me` — current user profile for the active JWT.
+   */
+  me() {
+    return this.http.get("/api/users/me");
+  }
+  /**
+   * Clears tokens from the token store.
+   * There is no server-side logout endpoint; access tokens remain valid until expiry
+   * (or until the user's `tokensValidFrom` watermark invalidates them).
+   */
+  async logout() {
+    await this.tokenStore?.clear();
+  }
+  /** True when the token store has an access token (sync stores only wait on Promise). */
+  async hasSession() {
+    const token = await this.tokenStore?.getAccessToken();
+    return Boolean(token);
+  }
+  async persistTokens(tokens) {
+    if (!this.tokenStore) {
+      return;
+    }
+    await this.tokenStore.setTokens({
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken
+    });
+  }
+};
+var SsoAuthResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** `GET /api/auth/sso/providers` (public). */
+  listProviders() {
+    return this.http.get("/api/auth/sso/providers", {
+      skipAuth: true
+    });
+  }
+  /**
+   * Absolute URL for `GET /api/auth/sso/:providerId/login`.
+   * Navigate the browser here to start the OIDC redirect.
+   */
+  getLoginUrl(providerId) {
+    if (!providerId) {
+      throw new Error("sso.getLoginUrl requires a providerId.");
+    }
+    return this.http.buildUrl(
+      `/api/auth/sso/${encodeURIComponent(providerId)}/login`
+    );
+  }
+};
+
+// src/resources/connections.ts
+var ConnectionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists connections in the workspace. */
+  list(options) {
+    return this.http.get("/api/connections", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single connection (secrets are never included). */
+  get(connectionId, options) {
+    return this.http.get(`/api/connections/${connectionId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+};
+
+// src/resources/discovery.ts
+var DiscoveryResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Returns the deployment's feature flags (storage, vector database, email,
+   * SSO, edition gating), letting a custom UI adapt to what is enabled.
+   */
+  enabledFeatures() {
+    return this.http.get("/api/discovery/enabled-features");
+  }
+};
+
+// src/core/pagination.ts
+async function* iteratePages(fetchPage) {
+  let page = 1;
+  while (true) {
+    const { data, pagination } = await fetchPage(page);
+    for (const item of data) {
+      yield item;
+    }
+    if (page >= pagination.totalPages || data.length === 0) {
+      return;
+    }
+    page += 1;
+  }
+}
+async function* iterateOffset(fetchBatch) {
+  let offset = 0;
+  while (true) {
+    const { items, pagination } = await fetchBatch(offset);
+    for (const item of items) {
+      yield item;
+    }
+    offset += items.length;
+    const exhausted = items.length === 0 || (pagination.hasMore !== void 0 ? !pagination.hasMore : offset >= pagination.total);
+    if (exhausted) {
+      return;
+    }
+  }
+}
+
+// src/resources/entities.ts
+var EntitiesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Returns one page of entities matching the filter. */
+  list(options = {}) {
+    return this.http.get("/api/objects", {
+      query: this.serializeListOptions(options)
+    });
+  }
+  /**
+   * Async-iterates every entity matching the filter, fetching pages lazily.
+   *
+   * ```ts
+   * for await (const invoice of client.entities.iterate({ objectTypeSlug: 'invoice' })) { ... }
+   * ```
+   */
+  iterate(options = {}) {
+    return iteratePages(async (page) => {
+      const result = await this.list({ ...options, page });
+      return { data: result.data ?? [], pagination: result.pagination };
+    });
+  }
+  /** Returns a single entity. Request `expansion: ['attributes']` for field values. */
+  get(entityId, options = {}) {
+    return this.http.get(`/api/objects/${entityId}`, {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Creates an entity. `attributes` are keyed by field ID. */
+  create(data, options = {}) {
+    return this.http.post("/api/objects", {
+      body: data,
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Partially updates an entity; supplied attributes are merged. */
+  update(entityId, data, options = {}) {
+    return this.http.patch(`/api/objects/${entityId}`, {
+      body: data,
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Soft-deletes an entity. */
+  delete(entityId) {
+    return this.http.delete(`/api/objects/${entityId}`);
+  }
+  /** Moves an entity to a new state (validated against the type's state machine). */
+  changeState(entityId, data) {
+    return this.http.post(
+      `/api/objects/${entityId}/state`,
+      { body: data }
+    );
+  }
+  /** Returns the entity's state changes, newest first. */
+  getStateHistory(entityId, options = {}) {
+    return this.http.get(
+      `/api/objects/${entityId}/state/history`,
+      { query: { limit: options.limit } }
+    );
+  }
+  /** Returns the current state and the transitions allowed from it. */
+  getStateTransitions(entityId) {
+    return this.http.get(
+      `/api/objects/${entityId}/state/transitions`
+    );
+  }
+  /** Imports pre-parsed rows into an entity type (SuperAdmin only). */
+  import(data) {
+    return this.http.post("/api/objects/import", {
+      body: data
+    });
+  }
+  /** Exports entities of a type as flat JSON rows. */
+  export(data) {
+    return this.http.post(
+      "/api/objects/export",
+      { body: data }
+    );
+  }
+  /** Returns the column headers and a sample row for importing (SuperAdmin only). */
+  getImportTemplate(entityTypeId) {
+    return this.http.get(
+      `/api/objects/import/template/${entityTypeId}`
+    );
+  }
+  serializeListOptions(options) {
+    return {
+      objectTypeId: options.objectTypeId,
+      objectTypeSlug: options.objectTypeSlug,
+      state: options.state,
+      states: options.states?.join(","),
+      ownerId: options.ownerId,
+      search: options.search,
+      sortBy: options.sortBy,
+      sortOrder: options.sortOrder,
+      page: options.page,
+      pageSize: options.pageSize,
+      expansion: serializeCsv(options.expansion)
+    };
+  }
+};
+
+// src/resources/entity-types.ts
+var EntityTypesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Lists entity types in the workspace. Request
+   * `expansion: ['attributeSchema', 'stateSchema']` for the field and state
+   * machine definitions the codegen CLI builds types from.
+   */
+  list(options = {}) {
+    return this.http.get("/api/object-types", {
+      query: {
+        includeDisabled: options.includeDisabled,
+        expansion: serializeCsv(options.expansion)
+      }
+    });
+  }
+  /** Returns a single entity type by ID. */
+  get(id, options = {}) {
+    return this.http.get(`/api/object-types/${id}`, {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Returns a single entity type by its URL-safe slug. */
+  getBySlug(slug, options = {}) {
+    return this.http.get(`/api/object-types/slug/${slug}`, {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+};
+
+// src/resources/approvals.ts
+var ApprovalsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * @param options.status `pending` (default) for actionable items, or `done` for history.
+   */
+  async inbox(options) {
+    return this.http.get("/api/approvals/inbox", {
+      query: { status: options?.status ?? "pending" }
+    });
+  }
+  async decide(approvalId, body) {
+    return this.http.post(`/api/approvals/${approvalId}/decide`, { body });
+  }
+};
+
+// src/streaming/execution-progress.ts
+var ExecutionProgressStream = class {
+  constructor(response, options) {
+    this.response = response;
+    this.options = options;
+  }
+  response;
+  options;
+  consumed = false;
+  [Symbol.asyncIterator]() {
+    return this.events();
+  }
+  async *events() {
+    if (this.consumed) {
+      throw new Error("This ExecutionProgressStream has already been consumed.");
+    }
+    this.consumed = true;
+    const body = this.response.body;
+    if (!body) {
+      return;
+    }
+    for await (const frame of parseSseEvents(body)) {
+      if (this.options?.signal?.aborted) {
+        return;
+      }
+      if (frame.data === null) {
+        continue;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(frame.data);
+      } catch {
+        continue;
+      }
+      if (!parsed || typeof parsed !== "object") {
+        continue;
+      }
+      yield {
+        event: frame.event,
+        data: parsed
+      };
+      if (frame.event === "execution.finished" || frame.event === "execution.error") {
+        return;
+      }
+    }
+  }
+};
+async function openExecutionStream(http, executionId, options) {
+  const response = await http.request("GET", `/api/executions/${executionId}/stream`, {
+    raw: true,
+    signal: options?.signal
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => void 0);
+    let parsed = body;
+    try {
+      parsed = body ? JSON.parse(body) : void 0;
+    } catch {
+    }
+    throw new LunnoaApiError({
+      status: response.status,
+      body: parsed,
+      method: "GET",
+      path: `/api/executions/${executionId}/stream`
+    });
+  }
+  return new ExecutionProgressStream(response, options);
+}
+
+// src/resources/executions.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "SUCCESS",
+  "FAILED",
+  "CANCELLED"
+]);
+var ExecutionTimeoutError = class extends Error {
+  constructor(executionId, timeoutMs) {
+    super(
+      `Execution ${executionId} did not finish within ${timeoutMs}ms. It is still running server-side; keep polling executions.get() or increase timeoutMs.`
+    );
+    this.executionId = executionId;
+    this.timeoutMs = timeoutMs;
+    this.name = "ExecutionTimeoutError";
+  }
+  executionId;
+  timeoutMs;
+};
+var ExecutionsResource = class {
+  constructor(http, workflowApps) {
+    this.http = http;
+    this.workflowApps = workflowApps;
+  }
+  http;
+  workflowApps;
+  catalogCache = null;
+  /**
+   * Starts a new execution of a workflow. Only the execution ID is returned;
+   * use {@link waitUntilFinished} or `get` to track progress.
+   */
+  execute(workflowId, inputData) {
+    return this.http.post(
+      `/api/executions/workflows/${workflowId}/execute`,
+      { body: { inputData: inputData ?? {} } }
+    );
+  }
+  /** Lists executions in the current workspace, most recently started first. */
+  list(options) {
+    return this.http.get("/api/executions", {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Returns a single execution. Request `expansion: ['status', 'executionPath']`
+   * for the business-readable step list custom UIs render progress from.
+   */
+  get(executionId, options) {
+    return this.http.get(`/api/executions/${executionId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Timeline-ready progress: `executionPath` plus catalogue icons/logos.
+   * Use this for a custom status bar / step list (not raw nodes/edges).
+   */
+  async getProgress(executionId) {
+    const execution = await this.get(executionId, {
+      expansion: [
+        "status",
+        "statusMessage",
+        "executionPath",
+        "pendingInput",
+        "source",
+        "name",
+        "startedAt",
+        "stoppedAt",
+        "output"
+      ]
+    });
+    return this.#toProgress(execution);
+  }
+  /**
+   * Opens the Public API SSE stream (`GET /executions/:id/stream`).
+   * Yields `execution.progress`, `loop.progress`, `execution.finished`, etc.
+   * For a simple timeline, prefer {@link watchProgress}.
+   */
+  stream(executionId, options) {
+    return openExecutionStream(this.http, executionId, options);
+  }
+  /**
+   * Live progress snapshots for a custom timeline UI.
+   * Subscribes to SSE `execution.progress` events (and enriches steps with icons).
+   * Completes when the execution reaches a terminal status or the signal aborts.
+   */
+  async *watchProgress(executionId, options) {
+    const stream = await this.stream(executionId, options);
+    for await (const frame of stream) {
+      if (frame.event === "execution.progress") {
+        const payload = frame.data;
+        yield await this.#progressFromPayload(payload);
+      } else if (frame.event === "execution.finished") {
+        yield await this.getProgress(executionId);
+        return;
+      } else if (frame.event === "execution.error") {
+        throw new Error(
+          typeof frame.data.message === "string" ? frame.data.message : `Execution stream error for ${executionId}`
+        );
+      }
+    }
+  }
+  /**
+   * Polls an execution with exponential backoff until it reaches a terminal
+   * status (`SUCCESS`, `FAILED`, `CANCELLED`) — or pauses in `NEEDS_INPUT`
+   * (unless `stopOnNeedsInput: false`). Resolves with the final execution
+   * including `status`, `statusMessage`, and `output`.
+   */
+  async waitUntilFinished(executionId, options = {}) {
+    const {
+      timeoutMs = 10 * 60 * 1e3,
+      initialDelayMs = 500,
+      maxDelayMs = 5e3,
+      backoffFactor = 1.5,
+      stopOnNeedsInput = true,
+      expansion = [],
+      signal,
+      sleep = defaultSleep
+    } = options;
+    const pollExpansion = Array.from(
+      /* @__PURE__ */ new Set(["status", "statusMessage", "output", ...expansion])
+    );
+    const startedAt = Date.now();
+    let waitedMs = 0;
+    let delay = initialDelayMs;
+    while (true) {
+      signal?.throwIfAborted();
+      const execution = await this.get(executionId, {
+        expansion: pollExpansion
+      });
+      const status = execution.status;
+      if (status && TERMINAL_STATUSES.has(status)) {
+        return execution;
+      }
+      if (stopOnNeedsInput && status === "NEEDS_INPUT") {
+        return execution;
+      }
+      const elapsed = Math.max(Date.now() - startedAt, waitedMs);
+      if (elapsed + delay > timeoutMs) {
+        throw new ExecutionTimeoutError(executionId, timeoutMs);
+      }
+      await sleep(delay);
+      waitedMs += delay;
+      delay = Math.min(delay * backoffFactor, maxDelayMs);
+    }
+  }
+  /**
+   * Resumes an execution paused in `NEEDS_INPUT` by submitting values for the
+   * waiting node. Identify the waiting node and its field schema via
+   * `expansion: ['pendingInput', 'executionPath']` (prefer `pendingInput` for
+   * the form contract; `executionPath` steps with status `NEEDS_INPUT` also
+   * carry the `nodeId`). Required fields from the schema must be present.
+   * The server acknowledges immediately and resumes asynchronously — follow
+   * up with {@link waitUntilFinished}.
+   */
+  async submitInput(executionId, nodeId, values) {
+    await this.http.post(
+      `/api/webhooks/executions/${executionId}/nodes/${nodeId}/input`,
+      { body: values }
+    );
+  }
+  /**
+   * Submit an approve/reject decision for a Request Approval node.
+   * Uses the authenticated Approvals API (not the public input webhook).
+   * Partial approvals keep the execution paused; terminal decisions resume it.
+   */
+  async submitApproval(executionId, nodeId, body) {
+    return this.http.post(
+      `/api/executions/${executionId}/nodes/${nodeId}/approvals`,
+      { body }
+    );
+  }
+  async #toProgress(execution) {
+    const path = execution.executionPath ?? [];
+    const steps = await this.#enrichSteps(path);
+    return {
+      executionId: execution.id,
+      status: execution.status,
+      statusMessage: execution.statusMessage ?? null,
+      name: execution.name ?? null,
+      source: execution.source ?? null,
+      startedAt: execution.startedAt,
+      stoppedAt: execution.stoppedAt ?? null,
+      steps,
+      pendingInput: execution.pendingInput,
+      output: execution.output,
+      activeStepIndex: findActiveStepIndex(steps)
+    };
+  }
+  async #progressFromPayload(payload) {
+    const steps = await this.#enrichSteps(payload.executionPath ?? []);
+    return {
+      executionId: payload.executionId,
+      status: payload.status ?? void 0,
+      statusMessage: payload.statusMessage,
+      name: payload.name,
+      source: payload.source,
+      startedAt: payload.startedAt,
+      stoppedAt: payload.stoppedAt,
+      steps,
+      pendingInput: payload.pendingInput,
+      output: payload.output,
+      activeStepIndex: findActiveStepIndex(steps)
+    };
+  }
+  async #enrichSteps(path) {
+    const catalog = await this.#loadCatalog();
+    return path.map((step) => {
+      const app = catalog?.find((a) => a.id === step.appId);
+      const action = step.actionId && Array.isArray(app?.actions) ? app.actions.find(
+        (a) => a && typeof a === "object" && a.id === step.actionId
+      ) : void 0;
+      const trigger = step.triggerId && Array.isArray(app?.triggers) ? app.triggers.find(
+        (t) => t && typeof t === "object" && t.id === step.triggerId
+      ) : void 0;
+      const iconUrl = typeof action?.iconUrl === "string" && action.iconUrl || typeof trigger?.iconUrl === "string" && trigger.iconUrl || null;
+      const durationMs = computeDurationMs(step.startTime, step.endTime);
+      return {
+        ...step,
+        appLogoUrl: app?.logoUrl ?? null,
+        iconUrl,
+        durationMs
+      };
+    });
+  }
+  async #loadCatalog() {
+    if (!this.workflowApps) {
+      return null;
+    }
+    if (!this.catalogCache) {
+      try {
+        this.catalogCache = await this.workflowApps.list();
+      } catch {
+        return null;
+      }
+    }
+    return this.catalogCache;
+  }
+};
+function findActiveStepIndex(steps) {
+  const idx = steps.findIndex(
+    (s) => s.status === "RUNNING" || s.status === "NEEDS_INPUT" || s.status === "RETRYING" || s.status === "WAITING" || s.status === "SCHEDULED"
+  );
+  return idx;
+}
+function computeDurationMs(start, end) {
+  if (!start || !end) return null;
+  const a = Date.parse(start);
+  const b = Date.parse(end);
+  if (Number.isNaN(a) || Number.isNaN(b) || b < a) return null;
+  return b - a;
+}
+function defaultSleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+
+// src/resources/knowledge.ts
+var KnowledgeResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists knowledge notebooks in the workspace. */
+  list(options = {}) {
+    return this.http.get("/api/knowledge", {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Returns a single knowledge notebook. */
+  get(knowledgeId, options = {}) {
+    return this.http.get(`/api/knowledge/${knowledgeId}`, {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Creates a knowledge notebook. Subject to the deployment's storage/vector infrastructure. */
+  create(data) {
+    return this.http.post("/api/knowledge", { body: data });
+  }
+  /** Updates a knowledge notebook. */
+  update(knowledgeId, data) {
+    return this.http.patch(`/api/knowledge/${knowledgeId}`, {
+      body: data
+    });
+  }
+  /** Deletes a knowledge notebook. */
+  delete(knowledgeId) {
+    return this.http.delete(`/api/knowledge/${knowledgeId}`);
+  }
+  /** Saves raw text into the notebook (chunked, embedded, and indexed server-side). */
+  saveUploadedText(knowledgeId, data) {
+    return this.http.post(
+      `/api/knowledge/${knowledgeId}/saveUploadedText`,
+      { body: data }
+    );
+  }
+  /** Lists the documents stored in a notebook. */
+  listDocuments(knowledgeId) {
+    return this.http.get(
+      `/api/knowledge/${knowledgeId}/documents`
+    );
+  }
+  /** Returns one document group (an uploaded document and its chunks). */
+  getDocumentGroup(knowledgeId, groupId) {
+    return this.http.get(
+      `/api/knowledge/${knowledgeId}/documents/${groupId}`
+    );
+  }
+  /** Deletes one document group from the notebook. */
+  deleteDocumentGroup(knowledgeId, groupId) {
+    return this.http.delete(
+      `/api/knowledge/${knowledgeId}/documents/${groupId}`
+    );
+  }
+};
+
+// src/resources/projects.ts
+var ProjectsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists projects in the workspace, most recently updated first. */
+  list(options) {
+    return this.http.get("/api/projects", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single project. */
+  get(projectId, options) {
+    return this.http.get(`/api/projects/${projectId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Creates a project. */
+  create(data) {
+    return this.http.post("/api/projects", { body: data });
+  }
+};
+
+// src/resources/queue-items.ts
+var QueueItemsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Returns one page of items in a queue (offset-based pagination). */
+  list(queueId, options = {}) {
+    return this.http.get(`/api/queues/${queueId}/items`, {
+      query: {
+        limit: options.limit,
+        offset: options.offset,
+        expansion: serializeCsv(options.expansion),
+        filterBy: serializeFilterBy(options.filterBy)
+      }
+    });
+  }
+  /** Async-iterates every item in a queue, fetching batches lazily. */
+  iterate(queueId, options = {}) {
+    return iterateOffset(async (offset) => {
+      const result = await this.list(queueId, { ...options, offset });
+      return {
+        items: result.items ?? [],
+        pagination: result.pagination
+      };
+    });
+  }
+  /** Returns a single queue item. */
+  get(queueId, itemId) {
+    return this.http.get(
+      `/api/queues/${queueId}/items/${itemId}`
+    );
+  }
+  /** Adds an item to a queue. */
+  create(queueId, data) {
+    return this.http.post(`/api/queues/${queueId}/items`, {
+      body: data
+    });
+  }
+  /** Adds many items to a queue in one call. */
+  bulkCreate(queueId, data) {
+    return this.http.post(
+      `/api/queues/${queueId}/items/bulk`,
+      { body: data }
+    );
+  }
+  /** Updates a queue item. */
+  update(queueId, itemId, data) {
+    return this.http.patch(
+      `/api/queues/${queueId}/items/${itemId}`,
+      { body: data }
+    );
+  }
+  /** Deletes a queue item. */
+  delete(queueId, itemId) {
+    return this.http.delete(
+      `/api/queues/${queueId}/items/${itemId}`
+    );
+  }
+  /** Returns items that are ready to be processed. */
+  listReady(queueId, options = {}) {
+    return this.http.get(`/api/queues/${queueId}/items/ready`, {
+      query: { limit: options.limit }
+    });
+  }
+  /** Returns items eligible for retry. */
+  listRetryable(queueId) {
+    return this.http.get(`/api/queues/${queueId}/items/retry`);
+  }
+  /** Returns items with the given status. */
+  listByStatus(queueId, status) {
+    return this.http.get(
+      `/api/queues/${queueId}/items/status/${status}`
+    );
+  }
+  /** Looks an item up by the external ID your system supplied. */
+  getByExternalId(queueId, externalId) {
+    return this.http.get(
+      `/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 }
+    });
+  }
+  /** Returns per-status and per-priority counts for the queue. */
+  stats(queueId) {
+    return this.http.get(`/api/queues/${queueId}/items/stats`);
+  }
+  /** Returns the recorded processing errors of an item. */
+  listErrors(queueId, itemId) {
+    return this.http.get(
+      `/api/queues/${queueId}/items/${itemId}/errors`
+    );
+  }
+  /** Updates the processing status of an item. */
+  updateStatus(queueId, itemId, status) {
+    return this.http.patch(
+      `/api/queues/${queueId}/items/${itemId}/status`,
+      { body: { status } }
+    );
+  }
+  /** Links an item to the workflow execution that processed it. */
+  linkExecution(queueId, itemId, executionId) {
+    return this.http.patch(
+      `/api/queues/${queueId}/items/${itemId}/link-execution`,
+      { body: { executionId } }
+    );
+  }
+  /** Queues the item for another processing attempt. */
+  retry(queueId, itemId) {
+    return this.http.post(
+      `/api/queues/${queueId}/items/${itemId}/retry`
+    );
+  }
+  /** Records a processing error on the item. */
+  addError(queueId, itemId, error) {
+    return this.http.post(
+      `/api/queues/${queueId}/items/${itemId}/error`,
+      { body: error }
+    );
+  }
+};
+
+// src/resources/queues.ts
+var QueuesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists queues in the workspace, ordered by priority then creation date. */
+  list(options) {
+    return this.http.get("/api/queues", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single queue. */
+  get(queueId, options) {
+    return this.http.get(`/api/queues/${queueId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Creates a queue. */
+  create(data) {
+    return this.http.post("/api/queues", { body: data });
+  }
+  /** Updates a queue. */
+  update(queueId, data) {
+    return this.http.patch(`/api/queues/${queueId}`, { body: data });
+  }
+  /** Deletes a queue. */
+  delete(queueId) {
+    return this.http.delete(`/api/queues/${queueId}`);
+  }
+  /** Returns aggregate statistics for a queue. */
+  stats(queueId) {
+    return this.http.get(`/api/queues/${queueId}/stats`);
+  }
+  /** Activates a queue. */
+  activate(queueId) {
+    return this.http.patch(`/api/queues/${queueId}/activate`);
+  }
+  /** Deactivates a queue. */
+  deactivate(queueId) {
+    return this.http.patch(`/api/queues/${queueId}/deactivate`);
+  }
+};
+
+// src/resources/runs.ts
+function isWorkflowDefinition(value) {
+  return typeof value === "object" && value !== null && value.kind === "workflow";
+}
+function isActionDefinition(value) {
+  return typeof value === "object" && value !== null && value.kind === "action";
+}
+function stepFromDefinition(step) {
+  if ("appId" in step && "actionId" in step && !("use" in step) && !("kind" in step)) {
+    return step;
+  }
+  if (isActionDefinition(step)) {
+    return {
+      appId: resolveActionAppId(step),
+      actionId: resolveActionId(step),
+      ...step.connection?.id ? { connectionId: step.connection.id } : {},
+      ...step.input ? { input: step.input } : {},
+      ...step.name ? { name: step.name } : {}
+    };
+  }
+  const use = step.use;
+  const input = {
+    ...use.input ?? {},
+    ...step.input ?? {}
+  };
+  return {
+    appId: resolveActionAppId(use),
+    actionId: resolveActionId(use),
+    ...use.connection?.id ? { connectionId: use.connection.id } : {},
+    ...Object.keys(input).length ? { input } : {},
+    ...step.name ?? use.name ? { name: step.name ?? use.name } : {}
+  };
+}
+function normalizeStartRunInput(input) {
+  if (isWorkflowDefinition(input)) {
+    return {
+      steps: input.steps.map(stepFromDefinition),
+      name: input.name ?? input.slug
+    };
+  }
+  if (Array.isArray(input)) {
+    return { steps: input.map((s) => stepFromDefinition(s)) };
+  }
+  return input;
+}
+var RunsResource = class {
+  constructor(http, executions) {
+    this.http = http;
+    this.executions = executions;
+  }
+  http;
+  executions;
+  /**
+   * Start a linear multi-step ad-hoc Execution.
+   *
+   * Accepts a `defineWorkflow` result, a step array, or an explicit
+   * `{ steps, projectId?, name? }` payload.
+   */
+  start(input) {
+    const options = normalizeStartRunInput(input);
+    if (!options.steps?.length) {
+      throw new Error("runs.start requires at least one step");
+    }
+    return this.http.post("/api/runs", {
+      body: options
+    });
+  }
+  /** Convenience: start and wait until terminal / NEEDS_INPUT. */
+  async startAndWait(input, waitOptions) {
+    const { id } = await this.start(input);
+    return this.executions.waitUntilFinished(id, {
+      ...waitOptions,
+      expansion: [
+        "executionPath",
+        "source",
+        ...waitOptions?.expansion ?? []
+      ]
+    });
+  }
+};
+
+// src/resources/tasks.ts
+var TasksResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists tasks (conversation threads) visible to the caller, most recently updated first. */
+  list(options) {
+    return this.http.get("/api/tasks", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single task. Request `expansion: ['messages']` for the conversation history. */
+  get(taskId, options) {
+    return this.http.get(`/api/tasks/${taskId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Creates a task (conversation thread) for an agent. */
+  create(agentId, data, options) {
+    return this.http.post(`/api/agents/${agentId}/tasks`, {
+      body: data,
+      query: serializeListQuery(options)
+    });
+  }
+  /** Updates the task name or description. */
+  update(taskId, data, options) {
+    return this.http.patch(`/api/tasks/${taskId}`, {
+      body: data,
+      query: serializeListQuery(options)
+    });
+  }
+  /** Permanently deletes a task and its messages. */
+  delete(taskId) {
+    return this.http.delete(`/api/tasks/${taskId}`);
+  }
+  /**
+   * Sends a message to an agent task and waits for the full agent turn to
+   * finish (non-streaming). Returns either a plain string or the assistant
+   * messages in AI SDK UIMessage format. For token-by-token output use
+   * `client.agentChat.streamMessage` instead.
+   */
+  message(agentId, taskId, message, options = {}) {
+    const uiMessage = typeof message === "string" ? {
+      id: generateMessageId2(),
+      role: "user",
+      parts: [{ type: "text", text: message }]
+    } : message;
+    return this.http.post(
+      `/api/agents/${agentId}/tasks/${taskId}/message`,
+      {
+        body: {
+          messages: [uiMessage],
+          ...options.chatMode ? { chatMode: options.chatMode } : {}
+        }
+      }
+    );
+  }
+};
+function generateMessageId2() {
+  const cryptoObj = globalThis.crypto;
+  if (cryptoObj?.randomUUID) {
+    return cryptoObj.randomUUID();
+  }
+  return `msg_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// src/resources/variables.ts
+var VariablesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists variables in the workspace. */
+  list(options) {
+    return this.http.get("/api/variables", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single variable. */
+  get(variableId, options) {
+    return this.http.get(`/api/variables/${variableId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Creates a variable. */
+  create(data) {
+    return this.http.post("/api/variables", { body: data });
+  }
+  /** Updates a variable. */
+  update(variableId, data) {
+    return this.http.patch(`/api/variables/${variableId}`, {
+      body: data
+    });
+  }
+  /** Deletes a variable. */
+  delete(variableId) {
+    return this.http.delete(`/api/variables/${variableId}`);
+  }
+};
+
+// src/resources/workflow-apps.ts
+var WorkflowAppsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists all workflow apps installed on the deployment. */
+  list() {
+    return this.http.get("/api/workflow-apps");
+  }
+  /**
+   * Creates a connection for an app where the connection type is
+   * non-interactive (API key, basic auth). OAuth connections require the
+   * browser flow inside the bundled UI and cannot be created here.
+   */
+  connect(appId, connectionId, value) {
+    return this.http.post(
+      `/api/workflow-apps/${appId}/connections/${connectionId}/connect`,
+      { body: value }
+    );
+  }
+};
+
+// src/resources/workflows.ts
+function stepToUpsertInput(step) {
+  const use = step.use;
+  return {
+    appId: resolveActionAppId(use),
+    actionId: resolveActionId(use),
+    connectionId: use.connection?.id,
+    input: {
+      ...use.input ?? {},
+      ...step.input ?? {}
+    },
+    name: step.name ?? use.name,
+    description: use.description
+  };
+}
+function workflowDefinitionToUpsert(def) {
+  return {
+    slug: def.slug,
+    name: def.name,
+    description: def.description,
+    isActive: def.isActive,
+    managedByCode: true,
+    steps: def.steps.map(stepToUpsertInput)
+  };
+}
+var WorkflowsResource = class {
+  constructor(http, executions) {
+    this.http = http;
+    this.executions = executions;
+  }
+  http;
+  executions;
+  /** Lists workflows in the current workspace. */
+  list(options) {
+    return this.http.get("/api/workflows", {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Returns a single workflow. Request `expansion: ['triggerNode']` to read
+   * the manual trigger's custom input field definitions.
+   */
+  get(workflowId, options) {
+    return this.http.get(`/api/workflows/${workflowId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Upsert a workflow by project-scoped slug from a linear step list.
+   * Prefer the CLI (`npx @lunnoa/client workflows deploy`) for happy-path deploy.
+   */
+  upsertBySlug(projectId, body) {
+    const payload = "kind" in body && body.kind === "workflow" ? workflowDefinitionToUpsert(body) : body;
+    return this.http.post(
+      `/api/projects/${projectId}/workflows/upsert`,
+      { body: payload }
+    );
+  }
+  /**
+   * Starts a new execution of the workflow with the given trigger inputs.
+   * Returns immediately with the execution ID.
+   */
+  execute(workflowId, inputs) {
+    return this.executions.execute(workflowId, inputs);
+  }
+  /**
+   * Convenience: execute the workflow and wait (poll with backoff) until it
+   * reaches a terminal status or pauses in `NEEDS_INPUT`.
+   */
+  async executeAndWait(workflowId, inputs, waitOptions) {
+    const { id } = await this.executions.execute(workflowId, inputs);
+    return this.executions.waitUntilFinished(id, waitOptions);
+  }
+  /**
+   * Triggers a workflow through its unauthenticated custom webhook endpoint
+   * (`POST /api/webhooks/workflows/:workflowId`). Only works for workflows
+   * with a webhook trigger. Returns the synchronous trigger output when the
+   * workflow responds synchronously.
+   */
+  triggerWebhook(workflowId, payload) {
+    return this.http.post(
+      `/api/webhooks/workflows/${workflowId}`,
+      { body: payload ?? {} }
+    );
+  }
+};
+
+// src/client.ts
+var LunnoaClient = class {
+  /** The underlying HTTP layer, exposed for advanced/escape-hatch requests. */
+  http;
+  /** Login, refresh, SSO discovery, and session helpers (Pattern B). */
+  auth;
+  agents;
+  tasks;
+  /** Hand-written SSE streaming client for agent chat (AI SDK UIMessage chunks). */
+  agentChat;
+  workflows;
+  executions;
+  /** Run catalogue actions as one-step ad-hoc Executions (`source: SDK`). */
+  actions;
+  /**
+   * Multi-step ad-hoc Executions (`source: SDK`) via `POST /api/runs`.
+   * Prefer `defineWorkflow` + `runs.start` for local linear chains.
+   */
+  runs;
+  /** Authenticated Approvals inbox (workspace API). */
+  approvals;
+  entities;
+  entityTypes;
+  knowledge;
+  queues;
+  queueItems;
+  variables;
+  connections;
+  projects;
+  workflowApps;
+  discovery;
+  constructor(options) {
+    this.http = new HttpClient(options);
+    this.auth = new AuthResource(this.http, this.http.tokenStore);
+    this.agents = new AgentsResource(this.http);
+    this.tasks = new TasksResource(this.http);
+    this.agentChat = new AgentChatClient(this.http);
+    this.workflowApps = new WorkflowAppsResource(this.http);
+    this.executions = new ExecutionsResource(this.http, this.workflowApps);
+    this.actions = new ActionsResource(this.http, this.executions);
+    this.runs = new RunsResource(this.http, this.executions);
+    this.approvals = new ApprovalsResource(this.http);
+    this.workflows = new WorkflowsResource(this.http, this.executions);
+    this.entities = new EntitiesResource(this.http);
+    this.entityTypes = new EntityTypesResource(this.http);
+    this.knowledge = new KnowledgeResource(this.http);
+    this.queues = new QueuesResource(this.http);
+    this.queueItems = new QueueItemsResource(this.http);
+    this.variables = new VariablesResource(this.http);
+    this.connections = new ConnectionsResource(this.http);
+    this.projects = new ProjectsResource(this.http);
+    this.discovery = new DiscoveryResource(this.http);
+  }
+};
+
+// src/cli/generate.ts
+function toCamelCase(input) {
+  const parts = input.replace(/[^a-zA-Z0-9]+/g, " ").trim().split(/\s+/);
+  if (parts.length === 0 || parts[0] === "") {
+    return "_";
+  }
+  const [first, ...rest] = parts;
+  const camel = first.charAt(0).toLowerCase() + first.slice(1) + rest.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+  return /^[0-9]/.test(camel) ? `_${camel}` : camel;
+}
+function toPascalCase(input) {
+  const camel = toCamelCase(input);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+function uniqueName(base, used) {
+  let name = base;
+  let counter = 2;
+  while (used.has(name)) {
+    name = `${base}${counter}`;
+    counter += 1;
+  }
+  used.add(name);
+  return name;
+}
+function quote(value) {
+  return JSON.stringify(value);
+}
+function docComment(lines, indent = "") {
+  const filtered = lines.filter(
+    (line) => !!line && line.trim().length > 0
+  );
+  if (filtered.length === 0) {
+    return "";
+  }
+  return `${indent}/**
+` + filtered.map((line) => `${indent} * ${line.replace(/\*\//g, "*\\/")}`).join("\n") + `
+${indent} */
+`;
+}
+function attributeFieldToTsType(field) {
+  const options = field.config?.options;
+  const optionUnion = options && options.length > 0 ? options.map((o) => quote(o.value)).join(" | ") : null;
+  switch (field.type) {
+    case "text":
+    case "longText":
+    case "richText":
+    case "url":
+    case "email":
+    case "phone":
+      return "string";
+    case "number":
+    case "currency":
+      return "number";
+    case "date":
+    case "datetime":
+      return "string";
+    case "boolean":
+      return "boolean";
+    case "dropdown":
+      return optionUnion ?? "string";
+    case "multiSelect":
+      return optionUnion ? `Array<${optionUnion}>` : "string[]";
+    case "user":
+    case "team":
+    case "entityReference":
+      return field.config?.multiple ? "string[]" : "string";
+    case "file":
+      return "unknown";
+    default:
+      return "unknown";
+  }
+}
+function workflowInputFieldToTsType(field) {
+  const selectUnion = field.selectOptions && field.selectOptions.length > 0 ? field.selectOptions.filter((o) => typeof o.value === "string").map((o) => quote(o.value)).join(" | ") : null;
+  let base;
+  switch (field.inputType) {
+    case "number":
+      base = "number";
+      break;
+    case "select":
+    case "dynamic-select":
+      base = selectUnion ?? "string";
+      break;
+    case "multi-select":
+    case "dynamic-multi-select":
+      base = selectUnion ? `Array<${selectUnion}>` : "string[]";
+      break;
+    case "switch": {
+      const on = field.switchOptions?.checked;
+      const off = field.switchOptions?.unchecked;
+      base = on && off ? `${quote(on)} | ${quote(off)}` : "string";
+      break;
+    }
+    case "json":
+      base = "unknown";
+      break;
+    case "map":
+      base = "Record<string, string>";
+      break;
+    case "text":
+    case "raw-text":
+    case "date":
+    case "date-time":
+    case "code":
+    case "file":
+      base = "string";
+      break;
+    default:
+      base = "unknown";
+  }
+  if (field.occurenceType === "multiple" && !base.endsWith("[]")) {
+    base = `Array<${base}>`;
+  }
+  return base;
+}
+function isFieldRequired(field) {
+  return Boolean(field.required);
+}
+function generateDeploymentModule(definitions) {
+  const chunks = [];
+  chunks.push(
+    `/* eslint-disable */
+/**
+ * Deployment-specific typed accessors for ${definitions.baseUrl}
+ *
+ * Generated by \`npx @lunnoa/client codegen\` \u2014 do not edit by hand.
+ * Re-run codegen whenever entity types, workflows, or agents change on
+ * the deployment.
+ */
+import type { LunnoaClient, Entity, Execution, ExecuteWorkflowResult, PaginatedEntities, Task, AgentChatStream, WaitUntilFinishedOptions, ListEntitiesOptions, UIMessage } from '@lunnoa/client';
+`
+  );
+  chunks.push(GENERATED_RUNTIME_HELPERS);
+  const usedTypeNames = /* @__PURE__ */ new Set();
+  const usedPropNames = /* @__PURE__ */ new Set();
+  const entityEntries = [];
+  for (const entityType of definitions.entityTypes) {
+    const typeName = uniqueName(toPascalCase(entityType.slug || entityType.name), usedTypeNames);
+    const prop = uniqueName(toCamelCase(entityType.slug || entityType.name), usedPropNames);
+    entityEntries.push({ prop, typeName, def: entityType });
+    chunks.push(generateEntityTypeBlock(entityType, typeName));
+  }
+  const usedWorkflowProps = /* @__PURE__ */ new Set();
+  const workflowEntries = [];
+  for (const workflow of definitions.workflows) {
+    const fields = workflow.triggerNode?.value?.customInputConfig ?? [];
+    const prop = uniqueName(toCamelCase(workflow.name), usedWorkflowProps);
+    const typeName = uniqueName(`${toPascalCase(workflow.name)}Inputs`, usedTypeNames);
+    workflowEntries.push({ prop, typeName, def: workflow, fields });
+    chunks.push(generateWorkflowInputsBlock(workflow, typeName, fields));
+  }
+  const usedAgentProps = /* @__PURE__ */ new Set();
+  const agentEntries = [];
+  for (const agent of definitions.agents) {
+    agentEntries.push({
+      prop: uniqueName(toCamelCase(agent.name), usedAgentProps),
+      def: agent
+    });
+  }
+  chunks.push(generateFactory(entityEntries, workflowEntries, agentEntries));
+  return chunks.join("\n");
+}
+function generateEntityTypeBlock(entityType, typeName) {
+  const fields = (entityType.attributeSchema?.sections ?? []).flatMap(
+    (section) => section.fields ?? []
+  );
+  const states = entityType.stateSchema?.states ?? [];
+  const fieldLines = fields.map((field) => {
+    const doc2 = docComment(
+      [field.label ?? field.name, field.helpText],
+      "  "
+    );
+    const optional = field.required ? "" : "?";
+    const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(field.id) ? field.id : quote(field.id);
+    return `${doc2}  ${key}${optional}: ${attributeFieldToTsType(field)};`;
+  }).join("\n");
+  const stateType = states.length > 0 ? states.map((s) => quote(s.id)).join(" | ") : "string";
+  const doc = docComment([
+    `${entityType.name} (\`${entityType.slug}\`)`,
+    entityType.description ?? void 0
+  ]);
+  return `${doc}export interface ${typeName}Attributes {
+${fieldLines || "  [fieldId: string]: unknown;"}
+}
+
+export type ${typeName}State = ${stateType};
+
+export type ${typeName} = Entity & { attributes?: ${typeName}Attributes; state?: ${typeName}State };
+`;
+}
+function generateWorkflowInputsBlock(workflow, typeName, fields) {
+  const doc = docComment([
+    `Trigger inputs for workflow "${workflow.name}"`,
+    workflow.description ?? void 0
+  ]);
+  if (fields.length === 0) {
+    return `${doc}export type ${typeName} = Record<string, unknown>;
+`;
+  }
+  const fieldLines = fields.map((field) => {
+    const fieldDoc = docComment([field.label, field.description], "  ");
+    const optional = isFieldRequired(field) ? "" : "?";
+    const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(field.id) ? field.id : quote(field.id);
+    return `${fieldDoc}  ${key}${optional}: ${workflowInputFieldToTsType(field)};`;
+  }).join("\n");
+  return `${doc}export interface ${typeName} {
+${fieldLines}
+}
+`;
+}
+function generateFactory(entityEntries, workflowEntries, agentEntries) {
+  const entityProps = entityEntries.map(({ prop, typeName, def }) => {
+    const doc = docComment([`${def.name} entities (\`${def.slug}\`)`], "    ");
+    return `${doc}    ${prop}: typedEntityAccessor<${typeName}Attributes, ${typeName}State>(client, ${quote(def.id)}),`;
+  }).join("\n");
+  const workflowProps = workflowEntries.map(({ prop, typeName, def }) => {
+    const doc = docComment(
+      [
+        `Workflow "${def.name}"`,
+        def.description ?? void 0,
+        def.isActive === false ? "NOTE: currently inactive on the deployment." : void 0
+      ],
+      "    "
+    );
+    return `${doc}    ${prop}: typedWorkflowAccessor<${typeName}>(client, ${quote(def.id)}),`;
+  }).join("\n");
+  const agentProps = agentEntries.map(({ prop, def }) => {
+    const doc = docComment(
+      [`Agent "${def.name}"`, def.description ?? void 0],
+      "    "
+    );
+    return `${doc}    ${prop}: typedAgentAccessor(client, ${quote(def.id)}),`;
+  }).join("\n");
+  return `/**
+ * Wraps a \`LunnoaClient\` with accessors typed from this deployment's own
+ * entity types, workflows, and agents.
+ *
+ * \`\`\`ts
+ * const lunnoa = createDeploymentClient(new LunnoaClient({ baseUrl, apiKey }));
+ * const open = await lunnoa.entities.invoice.list({ state: 'pending' });
+ * \`\`\`
+ */
+export function createDeploymentClient(client: LunnoaClient) {
+  return {
+    client,
+    entities: {
+${entityProps}
+    },
+    workflows: {
+${workflowProps}
+    },
+    agents: {
+${agentProps}
+    },
+  };
+}
+`;
+}
+var GENERATED_RUNTIME_HELPERS = `
+// ---------------------------------------------------------------------------
+// Small runtime helpers the generated accessors are built from.
+// ---------------------------------------------------------------------------
+
+function typedEntityAccessor<A, S extends string>(
+  client: LunnoaClient,
+  objectTypeId: string,
+) {
+  type Typed = Entity & { attributes?: A; state?: S };
+  return {
+    objectTypeId,
+    /** Lists entities of this type (attributes expanded by default). */
+    async list(
+      options: Omit<ListEntitiesOptions, 'objectTypeId' | 'objectTypeSlug' | 'state' | 'states'> & {
+        state?: S;
+        states?: S[];
+      } = {},
+    ): Promise<Omit<PaginatedEntities, 'data'> & { data: Typed[] }> {
+      const result = await client.entities.list({
+        expansion: ['attributes'],
+        ...options,
+        objectTypeId,
+      });
+      return result as Omit<PaginatedEntities, 'data'> & { data: Typed[] };
+    },
+    /** Async-iterates every entity of this type. */
+    iterate(
+      options: Omit<ListEntitiesOptions, 'objectTypeId' | 'objectTypeSlug' | 'page' | 'state' | 'states'> & {
+        state?: S;
+        states?: S[];
+      } = {},
+    ): AsyncGenerator<Typed, void, undefined> {
+      return client.entities.iterate({
+        expansion: ['attributes'],
+        ...options,
+        objectTypeId,
+      }) as AsyncGenerator<Typed, void, undefined>;
+    },
+    /** Returns a single entity of this type. */
+    async get(entityId: string): Promise<Typed> {
+      return (await client.entities.get(entityId, {
+        expansion: ['attributes'],
+      })) 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> {
+      return (await client.entities.create(
+        { ...data, objectTypeId } as never,
+        { expansion: ['attributes'] },
+      )) as Typed;
+    },
+    /** Partially updates an entity of this type. */
+    async update(
+      entityId: string,
+      data: { name?: string; attributes?: Partial<A>; ownerId?: string },
+    ): Promise<Typed> {
+      return (await client.entities.update(entityId, data as never, {
+        expansion: ['attributes'],
+      })) as Typed;
+    },
+    /** Soft-deletes an entity of this type. */
+    delete(entityId: string): Promise<boolean> {
+      return client.entities.delete(entityId);
+    },
+    /** Moves an entity of this type to a new state. */
+    changeState(entityId: string, newState: S, reason?: string) {
+      return client.entities.changeState(entityId, { newState, reason } as never);
+    },
+  };
+}
+
+function typedWorkflowAccessor<I>(client: LunnoaClient, workflowId: string) {
+  return {
+    workflowId,
+    /** Starts an execution with compile-time checked trigger inputs. */
+    execute(inputs: I): Promise<ExecuteWorkflowResult> {
+      return client.workflows.execute(workflowId, inputs as Record<string, unknown>);
+    },
+    /** Starts an execution and polls until it finishes (or pauses in NEEDS_INPUT). */
+    executeAndWait(inputs: I, waitOptions?: WaitUntilFinishedOptions): Promise<Execution> {
+      return client.workflows.executeAndWait(
+        workflowId,
+        inputs as Record<string, unknown>,
+        waitOptions,
+      );
+    },
+  };
+}
+
+function typedAgentAccessor(client: LunnoaClient, agentId: string) {
+  return {
+    agentId,
+    /** Creates a task (conversation thread) for this agent. */
+    createTask(data: { name?: string; id?: string; customIdentifier?: string } = {}): Promise<Task> {
+      return client.tasks.create(agentId, data as never);
+    },
+    /** Sends a message and streams the assistant turn (SSE, AI SDK chunks). */
+    streamMessage(
+      taskId: string,
+      message: string | UIMessage,
+      options?: { chatMode?: 'builder' | 'preview'; signal?: AbortSignal },
+    ): 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);
+    },
+  };
+}
+`;
+
+// src/cli/load-definition.ts
+import { pathToFileURL } from "url";
+import { resolve } from "path";
+import { access } from "fs/promises";
+import { constants as fsConstants } from "fs";
+async function fileExists(path) {
+  try {
+    await access(path, fsConstants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadDefinitionModule(pathArg) {
+  const absolute = resolve(process.cwd(), pathArg);
+  if (!await fileExists(absolute)) {
+    throw new Error(`Definition file not found: ${absolute}`);
+  }
+  const mod = await import(pathToFileURL(absolute).href);
+  return mod;
+}
+function pickWorkflowDefinition(mod) {
+  const candidates = [
+    mod.default,
+    mod.workflow,
+    ...Object.values(mod)
+  ];
+  for (const value of candidates) {
+    if (value && typeof value === "object" && value.kind === DEFINE_KINDS.workflow) {
+      return value;
+    }
+  }
+  throw new Error(
+    "No defineWorkflow() export found. Export the definition as default or `workflow`."
+  );
+}
+function pickAgentDefinition(mod) {
+  const candidates = [mod.default, mod.agent, ...Object.values(mod)];
+  for (const value of candidates) {
+    if (value && typeof value === "object" && value.kind === DEFINE_KINDS.agent) {
+      return value;
+    }
+  }
+  throw new Error(
+    "No defineAgent() export found. Export the definition as default or `agent`."
+  );
+}
+async function loadOptionalConfig() {
+  const candidates = [
+    "lunnoa.config.ts",
+    "lunnoa.config.mjs",
+    "lunnoa.config.js",
+    "lunnoa.config.json"
+  ];
+  for (const name of candidates) {
+    const absolute = resolve(process.cwd(), name);
+    if (!await fileExists(absolute)) {
+      continue;
+    }
+    if (name.endsWith(".json")) {
+      const { readFile } = await import("fs/promises");
+      const raw = await readFile(absolute, "utf8");
+      return JSON.parse(raw);
+    }
+    const mod = await import(pathToFileURL(absolute).href);
+    const cfg = mod.default ?? mod;
+    return {
+      url: cfg.url,
+      apiKey: cfg.apiKey,
+      projectId: cfg.projectId
+    };
+  }
+  return {};
+}
+
+// src/cli/index.ts
+function parseArgs(argv) {
+  const args = { command: argv[0], out: "./src/lunnoa" };
+  let i = 1;
+  if (args.command === "workflows" || args.command === "agents") {
+    args.subcommand = argv[1];
+    i = 2;
+    if (argv[2] && !argv[2].startsWith("--")) {
+      args.path = argv[2];
+      i = 3;
+    }
+  }
+  for (; i < argv.length; i += 1) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    switch (flag) {
+      case "--url":
+        args.url = value;
+        i += 1;
+        break;
+      case "--api-key":
+        args.apiKey = value;
+        i += 1;
+        break;
+      case "--access-token":
+        args.accessToken = value;
+        i += 1;
+        break;
+      case "--project-id":
+        args.projectId = value;
+        i += 1;
+        break;
+      case "--out":
+        args.out = value;
+        i += 1;
+        break;
+      default:
+        if (!args.path && !flag.startsWith("--")) {
+          args.path = flag;
+          break;
+        }
+        throw new Error(`Unknown option: ${flag}`);
+    }
+  }
+  return args;
+}
+var USAGE = `Usage:
+  npx @lunnoa/client codegen --url <deployment-url> --api-key <lna_key> [--out <dir>]
+  npx @lunnoa/client workflows deploy <path> --url <url> --api-key <key> --project-id <uuid>
+  npx @lunnoa/client agents deploy <path> --url <url> --api-key <key> --project-id <uuid>
+
+Options:
+  --url           Base URL of the Lunnoa Automate deployment
+  --api-key       Machine API key (lna_...)
+  --access-token  User JWT as an alternative to --api-key
+  --project-id    Project UUID (required for deploy)
+  --out           Output directory for lunnoa.generated.ts (codegen; default: ./src/lunnoa)
+
+Environment: LUNNOA_URL, LUNNOA_API_KEY, LUNNOA_PROJECT_ID
+Optional config file: lunnoa.config.ts | .mjs | .js | .json
+`;
+async function bindClient(args) {
+  const fileConfig = await loadOptionalConfig();
+  const url = args.url ?? process.env.LUNNOA_URL ?? fileConfig.url;
+  const apiKey = args.apiKey ?? process.env.LUNNOA_API_KEY ?? fileConfig.apiKey;
+  const accessToken = args.accessToken;
+  const projectId = args.projectId ?? process.env.LUNNOA_PROJECT_ID ?? fileConfig.projectId;
+  if (!url) {
+    throw new Error("Missing --url (or LUNNOA_URL / lunnoa.config).");
+  }
+  if (!apiKey && !accessToken) {
+    throw new Error(
+      "Missing --api-key (or LUNNOA_API_KEY) or --access-token."
+    );
+  }
+  return {
+    client: new LunnoaClient({ baseUrl: url, apiKey, accessToken }),
+    projectId,
+    url
+  };
+}
+async function fetchDefinitions(client, baseUrl) {
+  const entityTypes = await client.entityTypes.list({
+    expansion: ["attributeSchema", "stateSchema", "description"]
+  });
+  const workflowSummaries = await client.workflows.list({
+    expansion: ["description", "isActive"]
+  });
+  const workflows = [];
+  for (const summary of workflowSummaries) {
+    if (!summary.id) {
+      continue;
+    }
+    try {
+      const full = await client.workflows.get(summary.id, {
+        expansion: ["description", "isActive", "triggerNode"]
+      });
+      workflows.push(full);
+    } catch {
+      workflows.push(summary);
+    }
+  }
+  const agents = await client.agents.list({
+    expansion: ["description"]
+  });
+  return { baseUrl, entityTypes, workflows, agents };
+}
+async function runCodegen(args) {
+  const { client, url } = await bindClient(args);
+  console.log(`Querying ${url} ...`);
+  const definitions = await fetchDefinitions(client, url);
+  console.log(
+    `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);
+  await mkdir(outDir, { recursive: true });
+  const outFile = resolve2(outDir, "lunnoa.generated.ts");
+  await writeFile(outFile, moduleSource, "utf8");
+  console.log(`Wrote ${outFile}`);
+}
+async function deployWorkflow(args) {
+  if (!args.path) {
+    throw new Error("Missing definition path. Example: workflows deploy ./workflow.ts");
+  }
+  const { client, projectId } = await bindClient(args);
+  if (!projectId) {
+    throw new Error(
+      "Missing --project-id (or LUNNOA_PROJECT_ID / lunnoa.config)."
+    );
+  }
+  const mod = await loadDefinitionModule(args.path);
+  const def = pickWorkflowDefinition(mod);
+  const payload = workflowDefinitionToUpsert(def);
+  console.log(`Deploying workflow slug="${payload.slug}" to project ${projectId} ...`);
+  const result = await client.workflows.upsertBySlug(projectId, payload);
+  console.log(`Upserted workflow ${result.id} (${payload.slug})`);
+}
+async function deployAgent(args) {
+  if (!args.path) {
+    throw new Error("Missing definition path. Example: agents deploy ./agent.ts");
+  }
+  const { client, projectId } = await bindClient(args);
+  if (!projectId) {
+    throw new Error(
+      "Missing --project-id (or LUNNOA_PROJECT_ID / lunnoa.config)."
+    );
+  }
+  const mod = await loadDefinitionModule(args.path);
+  const def = pickAgentDefinition(mod);
+  const workflowIds = [];
+  for (const tool of def.tools ?? []) {
+    const unwrapped = "use" in tool && tool.use ? tool.use : tool;
+    if (unwrapped && typeof unwrapped === "object" && unwrapped.kind === DEFINE_KINDS.workflow) {
+      const wf = unwrapped;
+      const upserted = await client.workflows.upsertBySlug(
+        projectId,
+        workflowDefinitionToUpsert(wf)
+      );
+      if (upserted.id) {
+        workflowIds.push(upserted.id);
+        console.log(`Linked workflow tool ${upserted.id} (${wf.slug})`);
+      }
+    }
+  }
+  const payload = agentDefinitionToUpsert(def, { workflowIds });
+  console.log(`Deploying agent slug="${payload.slug}" to project ${projectId} ...`);
+  const result = await client.agents.upsertBySlug(projectId, payload);
+  console.log(`Upserted agent ${result.id} (${payload.slug})`);
+}
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.command || args.command === "--help" || args.command === "help") {
+    console.log(USAGE);
+    return;
+  }
+  if (args.command === "codegen") {
+    await runCodegen(args);
+    return;
+  }
+  if (args.command === "workflows" && args.subcommand === "deploy") {
+    await deployWorkflow(args);
+    return;
+  }
+  if (args.command === "agents" && args.subcommand === "deploy") {
+    await deployAgent(args);
+    return;
+  }
+  console.error(`Unknown command: ${args.command} ${args.subcommand ?? ""}
+`);
+  console.log(USAGE);
+  process.exitCode = 1;
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});