@loxtep/sdk 0.2.3 → 0.4.0

package/dist/authoring/toolbox.js

@@ -0,0 +1,166 @@
+/**
+ * Deterministic `toolbox` namespace — direct, typed platform calls with no model
+ * in the loop (R4.1, R4.7).
+ *
+ * Each method is a thin wrapper over the corresponding `LoxtepClient` namespace
+ * method. On success, it returns a typed result. On failure, it throws a
+ * `ToolboxOperationError` identifying the failed operation — it never falls back
+ * to a model.
+ */
+import { LoxtepError } from '../errors/base.js';
+// ─── Error type ──────────────────────────────────────────────────────────────
+/**
+ * Error thrown when a deterministic toolbox operation fails.
+ * Identifies the failed operation and namespace so the caller can
+ * distinguish it from other errors.
+ *
+ * Per R4.7 — the SDK never falls back to a model on failure.
+ */
+export class ToolboxOperationError extends LoxtepError {
+    /** The toolbox namespace where the failure occurred (e.g. 'dataProducts'). */
+    namespace;
+    /** The operation that failed (e.g. 'write', 'query', 'list'). */
+    operation;
+    constructor(namespace, operation, message, cause) {
+        super(`toolbox.${namespace}.${operation} failed: ${message}`, {
+            code: 'TOOLBOX_OPERATION_FAILED',
+            status_code: cause?.status_code,
+            details: {
+                namespace,
+                operation,
+                ...(cause instanceof Error ? { cause_message: cause.message } : {}),
+            },
+        });
+        this.name = 'ToolboxOperationError';
+        this.namespace = namespace;
+        this.operation = operation;
+        Object.setPrototypeOf(this, ToolboxOperationError.prototype);
+    }
+}
+/**
+ * Create a `Toolbox` — deterministic, typed platform operations with no model
+ * in the loop.
+ *
+ * On success each method returns a typed result. On failure, a
+ * `ToolboxOperationError` is thrown identifying the failed operation.
+ * The toolbox never falls back to an AI model.
+ *
+ * @param options - Client and project configuration.
+ * @returns A `Toolbox` instance.
+ */
+export function createToolbox(options) {
+    const { client, projectId } = options;
+    const dataProducts = {
+        async write(ref, event) {
+            try {
+                const writer = await client.data_products.get_writer(ref.name);
+                writer.write(event);
+                await writer.close();
+                return { success: true, events_written: 1 };
+            }
+            catch (err) {
+                throw new ToolboxOperationError('dataProducts', 'write', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+        async query(ref, sql) {
+            try {
+                const result = await client.data_products.query(ref.id, sql);
+                return { items: result.items, metadata: result.metadata };
+            }
+            catch (err) {
+                throw new ToolboxOperationError('dataProducts', 'query', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+        async get(ref) {
+            try {
+                return await client.data_products.get(ref.id);
+            }
+            catch (err) {
+                throw new ToolboxOperationError('dataProducts', 'get', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+        async list(filters) {
+            try {
+                const result = await client.data_products.list({
+                    domain_id: filters?.domain_id,
+                });
+                return result.items;
+            }
+            catch (err) {
+                throw new ToolboxOperationError('dataProducts', 'list', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+    };
+    const queues = {
+        async write(ref, event) {
+            try {
+                const writer = await client.queues.open_writer({
+                    bot_id: `toolbox-writer-${ref.name}`,
+                    queue_name: ref.name,
+                });
+                await writer.write(event);
+                await writer.close();
+            }
+            catch (err) {
+                throw new ToolboxOperationError('queues', 'write', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+        async getMetadata(ref) {
+            try {
+                const metadata = await client.queues.get_queue_metadata(ref.name);
+                return metadata;
+            }
+            catch (err) {
+                throw new ToolboxOperationError('queues', 'getMetadata', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+    };
+    const connections = {
+        async list() {
+            try {
+                const result = await client.connections.list();
+                return result.items;
+            }
+            catch (err) {
+                throw new ToolboxOperationError('connections', 'list', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+        async get(connectionId) {
+            try {
+                return await client.connections.get(connectionId);
+            }
+            catch (err) {
+                throw new ToolboxOperationError('connections', 'get', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+        async test(connectionId) {
+            try {
+                return await client.connections.test(connectionId);
+            }
+            catch (err) {
+                throw new ToolboxOperationError('connections', 'test', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+    };
+    const workflows = {
+        async list() {
+            try {
+                const result = await client.workflows.listWorkflows({ project_id: projectId });
+                return result.items;
+            }
+            catch (err) {
+                throw new ToolboxOperationError('workflows', 'list', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+        async getGraph(ref) {
+            try {
+                return await client.workflows.getWorkflowGraph(ref.id, projectId);
+            }
+            catch (err) {
+                throw new ToolboxOperationError('workflows', 'getGraph', err instanceof Error ? err.message : String(err), err);
+            }
+        },
+    };
+    return { dataProducts, queues, connections, workflows };
+}
+//# sourceMappingURL=toolbox.js.map

package/dist/authoring/toolbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolbox.js","sourceRoot":"","sources":["../../src/authoring/toolbox.ts"],"names":[],"mappings":"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"}

package/dist/authoring/triggers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Trigger builders for code-first data workflow authoring.
+ *
+ * Each builder accepts typed constants from the Generated_SDK_Artifact and
+ * returns a `TriggerSpec` describing the event source.
+ */
+import type { TriggerSpec, QueueRef, ConnectorRef } from './types.js';
+/**
+ * Trigger builder namespace. Each method constructs a `TriggerSpec` from a
+ * typed workspace constant.
+ *
+ * Usage:
+ * ```ts
+ * import { on } from '@loxtep/sdk/authoring';
+ * import { queues, connectors } from './.loxtep/generated/index';
+ *
+ * on.queueEvent(queues.orders_raw)
+ * on.connectorEvent(connectors.shopify_main)
+ * on.schedule('0 * * * *')
+ * on.webhook('/ingest/orders')
+ * ```
+ */
+export declare const on: {
+    /**
+     * Trigger on a queue event from a typed queue constant.
+     */
+    readonly queueEvent: (queue: QueueRef) => TriggerSpec;
+    /**
+     * Trigger on a connector event from a typed connector constant.
+     */
+    readonly connectorEvent: (connector: ConnectorRef) => TriggerSpec;
+    /**
+     * Trigger on a cron schedule.
+     */
+    readonly schedule: (cron: string) => TriggerSpec;
+    /**
+     * Trigger on an incoming webhook at the given path.
+     */
+    readonly webhook: (path: string) => TriggerSpec;
+};
+//# sourceMappingURL=triggers.d.ts.map

package/dist/authoring/triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../../src/authoring/triggers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,EAAE;IACb;;OAEG;iCACe,QAAQ,KAAG,WAAW;IAOxC;;OAEG;yCACuB,YAAY,KAAG,WAAW;IAOpD;;OAEG;8BACY,MAAM,KAAG,WAAW;IAOnC;;OAEG;6BACW,MAAM,KAAG,WAAW;CAM1B,CAAC"}

package/dist/authoring/triggers.js

@@ -0,0 +1,60 @@
+/**
+ * Trigger builders for code-first data workflow authoring.
+ *
+ * Each builder accepts typed constants from the Generated_SDK_Artifact and
+ * returns a `TriggerSpec` describing the event source.
+ */
+/**
+ * Trigger builder namespace. Each method constructs a `TriggerSpec` from a
+ * typed workspace constant.
+ *
+ * Usage:
+ * ```ts
+ * import { on } from '@loxtep/sdk/authoring';
+ * import { queues, connectors } from './.loxtep/generated/index';
+ *
+ * on.queueEvent(queues.orders_raw)
+ * on.connectorEvent(connectors.shopify_main)
+ * on.schedule('0 * * * *')
+ * on.webhook('/ingest/orders')
+ * ```
+ */
+export const on = {
+    /**
+     * Trigger on a queue event from a typed queue constant.
+     */
+    queueEvent(queue) {
+        return {
+            kind: 'queue',
+            ref: { id: queue.id, name: queue.name },
+        };
+    },
+    /**
+     * Trigger on a connector event from a typed connector constant.
+     */
+    connectorEvent(connector) {
+        return {
+            kind: 'connector',
+            ref: { id: connector.id, name: connector.type },
+        };
+    },
+    /**
+     * Trigger on a cron schedule.
+     */
+    schedule(cron) {
+        return {
+            kind: 'schedule',
+            schedule: cron,
+        };
+    },
+    /**
+     * Trigger on an incoming webhook at the given path.
+     */
+    webhook(path) {
+        return {
+            kind: 'webhook',
+            path,
+        };
+    },
+};
+//# sourceMappingURL=triggers.js.map

package/dist/authoring/triggers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.js","sourceRoot":"","sources":["../../src/authoring/triggers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG;IAChB;;OAEG;IACH,UAAU,CAAC,KAAe;QACxB,OAAO;YACL,IAAI,EAAE,OAAO;YACb,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;SACxC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,SAAuB;QACpC,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,GAAG,EAAE,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE;SAChD,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,IAAY;QACnB,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,IAAY;QAClB,OAAO;YACL,IAAI,EAAE,SAAS;YACf,IAAI;SACL,CAAC;IACJ,CAAC;CACO,CAAC"}

package/dist/authoring/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Types for the code-first data workflow authoring surface.
+ *
+ * A `DataWorkflowModule` is the developer-facing unit of authoring: it declares
+ * a trigger, an optional filter, and a handler that compiles down to the existing
+ * flow/workflow graph on deploy.
+ */
+/**
+ * Trigger specification describing what event starts a workflow.
+ */
+export interface TriggerSpec {
+    kind: 'queue' | 'connector' | 'schedule' | 'webhook';
+    /** Typed constant reference from the generated artifact (queue or connector). */
+    ref?: {
+        id: string;
+        name?: string;
+    };
+    /** Cron expression, for kind:'schedule'. */
+    schedule?: string;
+    /** URL path, for kind:'webhook'. */
+    path?: string;
+}
+/**
+ * A typed queue constant from the Generated_SDK_Artifact.
+ */
+export interface QueueRef {
+    id: string;
+    name: string;
+}
+/**
+ * A typed connector constant from the Generated_SDK_Artifact.
+ */
+export interface ConnectorRef {
+    id: string;
+    type: string;
+}
+/**
+ * Context object passed to the handler function during execution.
+ */
+export interface HandlerContext {
+    /** The workflow name. */
+    workflowName: string;
+    /** The attached instance ID. */
+    instanceId: string;
+    /** The project ID. */
+    projectId: string;
+}
+/**
+ * Spec for a Human Approval Node in the workflow graph.
+ * Events pause at this node pending a human decision, then route to
+ * an approved or rejected downstream path.
+ */
+export interface ApprovalNodeSpec {
+    kind: 'approval';
+    /** Node name, 1–128 characters. */
+    name: string;
+    /** Approval channel identifier, 1–256 characters. */
+    approvalChannel: string;
+    /** Hours before the approval request expires, 1–168. */
+    timeoutHours: number;
+    /** Optional human-readable description. */
+    description?: string;
+    /** Name of the upstream node feeding events into this node. */
+    upstream: string;
+    /** Name of the downstream node receiving approved events. */
+    approved?: string;
+    /** Name of the downstream node receiving rejected/expired events. */
+    rejected?: string;
+}
+/**
+ * Spec for an Agent Node in the workflow graph.
+ * Each event is processed by an AI model; the structured result flows downstream.
+ */
+export interface AgentNodeSpec {
+    kind: 'agent';
+    /** Node name, 1–128 characters. */
+    name: string;
+    /** Model identifier, 1–256 characters. */
+    modelId: string;
+    /** Prompt template rendered with event data, 1–10000 characters. */
+    promptTemplate: string;
+    /** Maximum seconds to wait for model response, 1–300. Defaults to 30. */
+    timeoutSeconds?: number;
+    /** JSON Schema describing expected model output structure, ≤50KB. */
+    outputSchema?: object;
+    /** Optional human-readable description. */
+    description?: string;
+    /** Name of the upstream node feeding events into this node. */
+    upstream: string;
+    /** Name of the downstream node receiving failed invocation events. */
+    error?: string;
+}
+/**
+ * A code-first data workflow module declaration.
+ * Created via `defineDataWorkflow()`.
+ */
+export interface DataWorkflowModule {
+    /** Workflow name, 1–64 characters (R3.1, R3.8). */
+    name: string;
+    /** 1–10 triggers that start this workflow (R3.1, R3.8). */
+    triggers: TriggerSpec[];
+    /** Optional event filter predicate. */
+    filter?: (event: unknown) => boolean;
+    /** The workflow handler function. */
+    handler: (ctx: HandlerContext, event: unknown) => Promise<void> | void;
+    /** Operation names requiring human approval, ≤100 entries, each 1–256 chars (R6.1). */
+    requireApproval?: string[];
+    /** Declarative graph nodes (approval gates, agent invocations) compiled to graph ops on deploy (R9.3). */
+    nodes?: Array<ApprovalNodeSpec | AgentNodeSpec>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/authoring/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/authoring/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;IACrD,iFAAiF;IACjF,GAAG,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAC;IACjB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,uCAAuC;IACvC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACrC,qCAAqC;IACrC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,0GAA0G;IAC1G,KAAK,CAAC,EAAE,KAAK,CAAC,gBAAgB,GAAG,aAAa,CAAC,CAAC;CACjD"}

package/dist/authoring/types.js

@@ -0,0 +1,9 @@
+/**
+ * Types for the code-first data workflow authoring surface.
+ *
+ * A `DataWorkflowModule` is the developer-facing unit of authoring: it declares
+ * a trigger, an optional filter, and a handler that compiles down to the existing
+ * flow/workflow graph on deploy.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/authoring/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/authoring/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/cli/commands/activity-cmd.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CLI: loxtep activity list [--source <s>] [--actor <a>] [--resource-type <t>] [--from <date>] [--to <date>]
+ *
+ * Lists activity and audit entries from the unified Activity/Audit read-model API.
+ * Ordered by UTC timestamp DESC with stable entry_id tie-break.
+ * Applies source/actor/resource-type/time-range filters combined with AND (R7.4).
+ * Synchronous read — R18.6 carve-out.
+ *
+ * Requirements: 7.4, 18.5
+ */
+import type { LoxtepClient } from '../../client/loxtep-client.js';
+import type { CliResult } from '../project-context.js';
+export interface ActivityListOptions {
+    source?: string;
+    actor?: string;
+    resource_type?: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+}
+/**
+ * Execute `loxtep activity list`.
+ *
+ * Lists activity and audit entries from the platform, applying optional filters.
+ * Does NOT require an attached project — operates at the organization level.
+ */
+export declare function runActivityListCommand(client: LoxtepClient, options?: ActivityListOptions): Promise<CliResult>;
+//# sourceMappingURL=activity-cmd.d.ts.map

package/dist/cli/commands/activity-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-cmd.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/activity-cmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAIvD,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,SAAS,CAAC,CA0DpB"}

package/dist/cli/commands/activity-cmd.js

@@ -0,0 +1,78 @@
+/**
+ * CLI: loxtep activity list [--source <s>] [--actor <a>] [--resource-type <t>] [--from <date>] [--to <date>]
+ *
+ * Lists activity and audit entries from the unified Activity/Audit read-model API.
+ * Ordered by UTC timestamp DESC with stable entry_id tie-break.
+ * Applies source/actor/resource-type/time-range filters combined with AND (R7.4).
+ * Synchronous read — R18.6 carve-out.
+ *
+ * Requirements: 7.4, 18.5
+ */
+const VALID_SOURCES = ['cli', 'sdk', 'mcp', 'ui'];
+/**
+ * Execute `loxtep activity list`.
+ *
+ * Lists activity and audit entries from the platform, applying optional filters.
+ * Does NOT require an attached project — operates at the organization level.
+ */
+export async function runActivityListCommand(client, options) {
+    try {
+        // Validate source filter
+        if (options?.source && !VALID_SOURCES.includes(options.source)) {
+            return {
+                exitCode: 1,
+                stdout: [],
+                stderr: [
+                    `Invalid source filter: '${options.source}'. Must be one of: ${VALID_SOURCES.join(', ')}.`,
+                ],
+            };
+        }
+        const filters = {};
+        if (options?.source)
+            filters.source = options.source;
+        if (options?.actor)
+            filters.actor = options.actor;
+        if (options?.resource_type)
+            filters.resource_type = options.resource_type;
+        if (options?.from)
+            filters.start = options.from;
+        if (options?.to)
+            filters.end = options.to;
+        if (options?.limit != null)
+            filters.limit = options.limit;
+        const result = await client.activity.list(filters);
+        const { entries } = result;
+        if (entries.length === 0) {
+            return { exitCode: 0, stdout: ['No activity entries found.'], stderr: [] };
+        }
+        const lines = [];
+        for (const entry of entries) {
+            const kindTag = entry.kind === 'action_trace' ? 'TRACE' : 'AUDIT';
+            const outcomeTag = entry.outcome ? ` [${entry.outcome}]` : '';
+            const sourceTag = entry.source ? ` (${entry.source})` : '';
+            lines.push(`${entry.timestamp}  ${kindTag}${outcomeTag}${sourceTag}  ${entry.operation_name}`);
+            if (entry.workflow_name) {
+                lines.push(`  Workflow: ${entry.workflow_name}`);
+            }
+            if (entry.actor) {
+                lines.push(`  Actor: ${entry.actor}`);
+            }
+            if (entry.target_resource) {
+                lines.push(`  Target: ${entry.target_resource}`);
+            }
+            if (entry.resource_type && entry.resource_id) {
+                lines.push(`  Resource: ${entry.resource_type}/${entry.resource_id}`);
+            }
+            if (entry.skill_name) {
+                lines.push(`  Skill: ${entry.skill_name}`);
+            }
+            lines.push('');
+        }
+        return { exitCode: 0, stdout: lines, stderr: [] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, stdout: [], stderr: [`Failed to list activity: ${message}`] };
+    }
+}
+//# sourceMappingURL=activity-cmd.js.map

package/dist/cli/commands/activity-cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-cmd.js","sourceRoot":"","sources":["../../../src/cli/commands/activity-cmd.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/attach-cmd.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `loxtep attach [--instance <id>]`
+ *
+ * Links the project to an existing Instance using the same connection mechanism
+ * the Platform_UI uses (client.projects + client.instances / update_project).
+ *
+ * On success: writes resolved `instance_id` + `api_url` atomically into
+ * `.loxtep/project.json`, including a `repository` block when the project is
+ * GitHub-bound (R17.2) and omitting it when unbound (R17.3).
+ *
+ * On failure: exits non-zero, prints the failure reason, and leaves
+ * `.loxtep/project.json` byte-unchanged (R1.9).
+ */
+import type { LoxtepClient } from '../../client/loxtep-client.js';
+import type { Project } from '../../client/projects-types.js';
+import { type CliResult, type ProjectRepository } from '../project-context.js';
+export interface AttachOptions {
+    /** Explicit instance ID from `--instance <id>`. When omitted, the org's sole instance is used. */
+    instanceId?: string;
+    /** Working directory override (defaults to `process.cwd()`). */
+    cwd?: string;
+}
+/**
+ * Project the GitHub binding fields from a project record into a
+ * {@link ProjectRepository} block, or `undefined` when the project is unbound.
+ *
+ * A project is considered bound when it has both `github_repo_url` and
+ * `github_repo_name` present and non-empty.
+ */
+export declare function projectToRepository(project: Project): ProjectRepository | undefined;
+/**
+ * Core attach logic, separated from CLI wiring for testability.
+ *
+ * Returns a {@link CliResult} so the thin CLI `main()` can map `exitCode` to
+ * `process.exitCode` without spawning a process.
+ */
+export declare function runAttach(client: LoxtepClient, options?: AttachOptions): Promise<CliResult>;
+//# sourceMappingURL=attach-cmd.d.ts.map

package/dist/cli/commands/attach-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-cmd.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/attach-cmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAIL,KAAK,SAAS,EAEd,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,aAAa;IAC5B,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAoBnF;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,SAAS,CAAC,CAwEpB"}