@loxtep/sdk 0.2.3 → 0.3.0

package/README.md

@@ -249,3 +249,144 @@ loxtep queue info <data-product-id>
 loxtep data-products query <data-product-id> "SELECT * FROM t LIMIT 10"
 loxtep metrics rate-limits
 ```
+
+## Module exports
+
+The SDK also ships standalone modules for configuration, authentication,
+code generation, skill scoping, and workflow authoring. Import them directly
+from the relevant subpath.
+
+### `config` module
+
+```typescript
+import { loadConfig, loadConfigSync, saveConfig } from '@loxtep/sdk/config';
+```
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `loadConfig` | function | Load config from env vars and optional file (async). Precedence: env > file > defaults |
+| `loadConfigSync` | function | Synchronous variant of `loadConfig` using `readFileSync` |
+| `saveConfig` | function | Persist config (api_url, org/project/instance IDs) to file. No secrets written to disk |
+| `parseStreamsPartial` | function | Extract a partial bus config from unknown JSON, keeping only valid stream resource keys |
+| `getConfigDir` | function | Return the default config directory path (`~/.loxtep`) |
+| `getDefaultConfigPath` | function | Return the default config file path (`~/.loxtep/config.json`) |
+| `buildAuthServiceUrl` | function | Build the full URL for auth endpoints (`/auth/login`, `/auth/refresh`) with path prefix |
+| `extendClientBaseUrl` | function | Extend `api_url` with a microservice path segment, avoiding duplication |
+| `buildPlatformRequestUrl` | function | Build a full request URL for the shared control-plane host, handling microservice routing |
+| `resolveAutoConfig` | function | Resolve configuration with full precedence: env > explicit > workspace files |
+
+### `auth` module
+
+```typescript
+import { login, refresh, browserLogin, TokenManager } from '@loxtep/sdk/auth';
+```
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `decodeJwtPayload` | function | Decode JWT payload to read `exp` (expiry) without verification. Client-side only |
+| `login` | function | Authenticate with email/password via `POST /auth/login`. Returns access + refresh tokens |
+| `refresh` | function | Refresh an access token via `POST /auth/refresh` |
+| `browserLogin` | function | Run OAuth 2.1 browser-based login flow with a localhost callback server |
+| `TokenManager` | class | In-memory token manager with auto-refresh support. No tokens persisted to disk |
+| `LoginMfaRequiredError` | class | Error thrown when login returns 403 and the user must supply a TOTP code |
+
+### `codegen` module
+
+```typescript
+import { loadWorkspaceContext, deriveKey, normalizeContext, emitArtifact, writeArtifact, computeCounts } from '@loxtep/sdk/codegen';
+```
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `loadWorkspaceContext` | function | Fetch all workspace resources from the control plane and assemble a `WorkspaceContext` |
+| `deriveKey` | function | Derive a deterministic, valid TypeScript identifier key from a resource name |
+| `normalizeContext` | function | Transform raw `WorkspaceContext` into canonical `NormalizedContext` with stable keys and id-sorted ordering |
+| `emitArtifact` | function | Render a `NormalizedContext` into a complete TypeScript source string with `as const` exports |
+| `writeArtifact` | function | Atomic file write of the generated artifact; returns per-resource-type counts |
+| `computeCounts` | function | Compute per-resource-type counts from a `NormalizedContext` |
+
+### `skills` module
+
+```typescript
+import { checkScope, parseSkillYaml, loadSkillsFromDirectory } from '@loxtep/sdk/skills';
+```
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `checkScope` | function | Fail-closed scope decision: check whether an operation on a resource is permitted by a skill |
+| `checkScopeByName` | function | Resolve a skill by name from a map and check scope in one step |
+| `parseSkillYaml` | function | Parse a YAML string into a validated `SkillDefinition` |
+| `loadSkillFromFile` | function | Load a single skill definition from a `.yaml` file path |
+| `loadSkillsFromDirectory` | function | Load all skill definitions from a `.loxtep/skills/` directory |
+| `validateSkillReferences` | function | Validate all skill resource references against the loaded `WorkspaceContext` |
+| `formatSkillValidationErrors` | function | Format skill validation errors into human-readable messages |
+| `SkillDefinitionSchema` | object | Zod schema for validating skill definition YAML structure |
+
+### `authoring` module
+
+```typescript
+import { defineDataWorkflow, on, createToolbox, agent } from '@loxtep/sdk/authoring';
+```
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `defineDataWorkflow` | function | Validate and return a `DataWorkflowModule` spec. Throws `ValidationError` on invalid input |
+| `on` | object | Trigger builders: `queueEvent`, `connectorEvent`, `schedule`, `webhook` |
+| `createToolbox` | function | Create a deterministic typed platform-call toolbox (no model in the loop) |
+| `agent` | function | Agentic operation entry point with scope enforcement and action trace |
+| `validateAgentOptions` | function | Validate agent options (prompt length, skills references) against available skills |
+| `computeReachableScope` | function | Compute the union of all resource scopes from supplied skill definitions |
+| `enforceAgentScope` | function | Check whether a resource access is within the merged scope of the agent's skills |
+| `createScopeGuardedToolbox` | function | Create a scope-guarded proxy that enforces scope and records traces before every call |
+| `compileModule` | function | Pure compiler: lower a `DataWorkflowModule` into `GraphPatchOp[]` for deployment |
+| `computeRemovalSet` | function | Compute workflows present on instance but absent from project modules (for cleanup) |
+| `ActionTrace` | class | Mutable action trace recorder with monotonically increasing sequence numbers |
+| `AgentScopeError` | class | Error thrown when an agentic operation is blocked due to a scope violation |
+| `ToolboxOperationError` | class | Error thrown when a toolbox operation fails (network, validation, or platform error) |
+
+### `http` module
+
+```typescript
+import { signRequest, LoxtepHttpClient } from '@loxtep/sdk/http';
+```
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `signRequest` | function | Sign an HTTP request with AWS SigV4 for API Gateway (`execute-api`). Returns headers including `Authorization` and `x-amz-*` |
+| `LoxtepHttpClient` | class | HTTP client that signs requests with AWS SigV4 and attaches JWT. Provides `get`, `post`, `put`, `delete` helpers with retry on 5xx/network errors and typed Loxtep errors on 4xx |
+
+### `checkpoint` module
+
+```typescript
+import { createMemoryCheckpointStore } from '@loxtep/sdk/checkpoint';
+```
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `createMemoryCheckpointStore` | function | Create an in-memory checkpoint store for stream/replay resume. Suitable for tests or single-process use |
+
+### Error classes
+
+```typescript
+import { AuthorizationError, ConflictError, ValidationError, DefinitionValidationError, SchemaValidationError, CheckpointError, parseHttpError } from '@loxtep/sdk/errors';
+```
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `AuthorizationError` | class | 403 — Insufficient permissions |
+| `ConflictError` | class | 409 — Resource already exists or version conflict |
+| `ValidationError` | class | 400 — Invalid input with optional `field_errors` array |
+| `DefinitionValidationError` | class | 400 — Payload doesn't match data product definition (schema validation failures) |
+| `SchemaValidationError` | class | Alias for `DefinitionValidationError` (backend terminology) |
+| `CheckpointError` | class | 500 — Failed to save or load a stream checkpoint |
+| `parseHttpError` | function | Map an HTTP status code and response body to the appropriate typed Loxtep error class |
+
+### `DataProductResolver` class
+
+```typescript
+import { DataProductResolver } from '@loxtep/sdk/client';
+```
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `DataProductResolver` | class | Resolves a data product name or UUID into full runtime configuration (queue name, bot_id, stream bus resources). Caches results in memory. Used internally by `client.data_products.get_writer`/`get_reader` |

package/dist/authoring/agent.d.ts

@@ -0,0 +1,164 @@
+/**
+ * `agent()` entry point — agentic operations with input validation,
+ * client-side scope enforcement, and action trace recording.
+ *
+ * The agentic path accepts a prompt and a skills allowlist, validates inputs,
+ * enforces scope boundaries before any platform call, and records every
+ * operation as an ordered ActionTraceEntry.
+ *
+ * Requirements: 4.2, 4.3, 4.4, 4.5, 4.6, 7.1
+ */
+import { LoxtepError } from '../errors/base.js';
+import type { SkillDefinition, SkillScope, Operation, ScopeDecision } from '../skills/types.js';
+import type { HandlerContext } from './types.js';
+import type { Toolbox } from './toolbox.js';
+/**
+ * A reference to a skill from the Generated_SDK_Artifact.
+ * Must contain at minimum a `name` field that matches a loaded skill definition.
+ */
+export interface SkillRef {
+    name: string;
+}
+/**
+ * Options for the `agent()` entry point.
+ */
+export interface AgentOptions {
+    /** The prompt for the agentic operation. 1–10,000 characters, non-empty (R4.2, R4.6). */
+    prompt: string;
+    /** Skills allowlist. 1–50 refs, each present in the generated artifact (R4.2, R4.6). */
+    skills: SkillRef[];
+}
+/**
+ * Outcome of an action trace entry.
+ */
+export type ActionOutcome = 'succeeded' | 'failed' | 'blocked';
+/**
+ * A single entry in the action trace recording an operation's execution.
+ * Ordered by execution start time (monotonic sequence, R4.5, R7.1).
+ */
+export interface ActionTraceEntry {
+    /** Monotonically increasing sequence number (1-based). */
+    seq: number;
+    /** The type of operation: deterministic toolbox call or agentic step. */
+    kind: 'toolbox' | 'agentic' | 'scope_check';
+    /** The operation name (e.g. 'dataProducts.write', 'scope_enforcement'). */
+    operationName: string;
+    /** The target resource identifier, if applicable. */
+    targetResource?: string;
+    /** Execution start time (ISO 8601 UTC). */
+    startedAt: string;
+    /** Execution completion time (ISO 8601 UTC). */
+    completedAt: string;
+    /** Outcome of the operation. */
+    outcome: ActionOutcome;
+    /** Error message if the operation failed or was blocked. */
+    error?: string;
+}
+/**
+ * The result of an `agent()` invocation.
+ */
+export interface AgentResult {
+    /** Whether the overall agentic operation succeeded. */
+    success: boolean;
+    /** The action trace recording every operation executed. */
+    trace: ActionTraceEntry[];
+    /** Error if the operation terminated due to a scope violation or failure. */
+    error?: {
+        code: string;
+        message: string;
+        deniedResource?: string;
+    };
+}
+/**
+ * Internal context for the agent execution environment.
+ */
+export interface AgentExecutionContext {
+    /** The handler context (workflow name, instance, project). */
+    handlerContext: HandlerContext;
+    /** The resolved skill definitions for the supplied skills. */
+    skillDefinitions: SkillDefinition[];
+    /** The available toolbox for making platform calls. */
+    toolbox: Toolbox;
+    /** The set of valid skill names from the generated artifact. */
+    availableSkillNames: Set<string>;
+}
+/**
+ * Validate the agent options (prompt + skills).
+ * Throws ValidationError on invalid input (R4.6).
+ *
+ * @param options - The agent options to validate.
+ * @param availableSkillNames - Set of skill names present in the generated artifact.
+ */
+export declare function validateAgentOptions(options: AgentOptions, availableSkillNames: Set<string>): void;
+/**
+ * Compute the union of all resource scopes from the supplied skill definitions.
+ * The reachable set is the union of all skills' scopes (R4.3).
+ *
+ * @param skills - The skill definitions to union.
+ * @returns A merged SkillScope representing all reachable resources.
+ */
+export declare function computeReachableScope(skills: SkillDefinition[]): SkillDefinition;
+/**
+ * Check whether a resource access is within the merged scope of the agent's skills.
+ * Blocks out-of-scope reaches before any platform call (R4.4).
+ *
+ * @param mergedSkill - The merged skill scope (union of all supplied skills).
+ * @param resourceType - The resource type being accessed.
+ * @param resourceId - The resource identifier being accessed.
+ * @param operation - The operation being attempted.
+ * @returns The scope decision.
+ */
+export declare function enforceAgentScope(mergedSkill: SkillDefinition, resourceType: keyof SkillScope, resourceId: string, operation: Operation): ScopeDecision;
+/**
+ * Mutable action trace recorder. Assigns monotonically increasing sequence
+ * numbers to each entry (R4.5, R7.1).
+ */
+export declare class ActionTrace {
+    private readonly entries;
+    private seq;
+    /**
+     * Record a completed operation in the trace.
+     */
+    record(entry: Omit<ActionTraceEntry, 'seq'>): ActionTraceEntry;
+    /**
+     * Get all recorded entries in order.
+     */
+    getEntries(): ActionTraceEntry[];
+    /**
+     * Get the current sequence number (number of recorded entries).
+     */
+    getSeq(): number;
+}
+/**
+ * Error thrown when an agentic operation is blocked due to a scope violation.
+ */
+export declare class AgentScopeError extends LoxtepError {
+    readonly deniedResource: string;
+    constructor(deniedResource: string, code: string, message: string);
+}
+/**
+ * The `agent()` entry point for agentic operations within a data workflow handler.
+ *
+ * Validates inputs (R4.6), restricts the model to the supplied skills (R4.3),
+ * blocks out-of-scope reaches before any platform call (R4.4), and records
+ * every operation in an ordered action trace (R4.5, R7.1).
+ *
+ * @param ctx - Handler context (workflow name, instance, project).
+ * @param options - Agent options (prompt + skills allowlist).
+ * @param execContext - Execution context with resolved skills + toolbox.
+ * @returns The agent result including the action trace.
+ * @throws {ValidationError} If prompt or skills are invalid (R4.6).
+ */
+export declare function agent(ctx: HandlerContext, options: AgentOptions, execContext: AgentExecutionContext): Promise<AgentResult>;
+/**
+ * Create a scope-guarded proxy around the toolbox. Every method call goes through
+ * scope enforcement first; if denied, the call is blocked, a trace entry is recorded,
+ * and an AgentScopeError is thrown terminating the operation (R4.4).
+ *
+ * @param toolbox - The underlying toolbox.
+ * @param mergedSkill - The merged skill scope for enforcement.
+ * @param trace - The action trace to record operations.
+ * @returns A guarded toolbox that enforces scope and records traces.
+ */
+export declare function createScopeGuardedToolbox(toolbox: Toolbox, mergedSkill: SkillDefinition, trace: ActionTrace): Toolbox;
+//# sourceMappingURL=agent.d.ts.map

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

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