@levelcode/sdk 0.2.2 → 0.2.3

package/dist/common/src/types/skill.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod/v4';
+/**
+ * Zod schema for skill frontmatter metadata.
+ */
+export declare const SkillMetadataSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/**
+ * Zod schema for skill frontmatter (parsed from YAML).
+ */
+export declare const SkillFrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    license: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type SkillFrontmatter = z.infer<typeof SkillFrontmatterSchema>;
+/**
+ * Full skill definition including content and source path.
+ */
+export declare const SkillDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    license: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    content: z.ZodString;
+    filePath: z.ZodString;
+}, z.core.$strip>;
+export type SkillDefinition = z.infer<typeof SkillDefinitionSchema>;
+/**
+ * Collection of skills keyed by skill name.
+ */
+export type SkillsMap = Record<string, SkillDefinition>;

package/dist/common/src/types/source.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Represents a source of data.
+ *
+ * By default, can be a value or a promise.
+ *
+ * In the case that the type is a not function itself, this can also be a function that returns the value or promise.
+ */
+export type Source<T> = T | Promise<T> | (T extends (...args: unknown[]) => unknown ? never : () => T | Promise<T>);

package/dist/common/src/types/spawn.d.ts

@@ -0,0 +1,8 @@
+import type { ChildProcess, SpawnOptions } from 'child_process';
+/**
+ * Spawn function for running shell commands.
+ *
+ * Compatible with `child_process.spawn` from Node.js.
+ * Returns ChildProcess to support full streaming capabilities (stdin, stdout, stderr).
+ */
+export type LevelCodeSpawn = (command: string, args?: readonly string[], options?: SpawnOptions) => ChildProcess;

package/dist/common/src/types/team-config-schemas.d.ts

@@ -0,0 +1,217 @@
+import { z } from 'zod';
+export declare const teamRoleSchema: z.ZodEnum<{
+    researcher: "researcher";
+    reviewer: "reviewer";
+    coordinator: "coordinator";
+    cto: "cto";
+    "vp-engineering": "vp-engineering";
+    director: "director";
+    fellow: "fellow";
+    "distinguished-engineer": "distinguished-engineer";
+    "principal-engineer": "principal-engineer";
+    "senior-staff-engineer": "senior-staff-engineer";
+    "staff-engineer": "staff-engineer";
+    manager: "manager";
+    "sub-manager": "sub-manager";
+    "senior-engineer": "senior-engineer";
+    "super-senior": "super-senior";
+    "mid-level-engineer": "mid-level-engineer";
+    "junior-engineer": "junior-engineer";
+    scientist: "scientist";
+    designer: "designer";
+    "product-lead": "product-lead";
+    tester: "tester";
+    intern: "intern";
+    apprentice: "apprentice";
+}>;
+export declare const devPhaseSchema: z.ZodEnum<{
+    planning: "planning";
+    "pre-alpha": "pre-alpha";
+    alpha: "alpha";
+    beta: "beta";
+    production: "production";
+    mature: "mature";
+}>;
+export declare const teamMemberSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    name: z.ZodString;
+    role: z.ZodEnum<{
+        researcher: "researcher";
+        reviewer: "reviewer";
+        coordinator: "coordinator";
+        cto: "cto";
+        "vp-engineering": "vp-engineering";
+        director: "director";
+        fellow: "fellow";
+        "distinguished-engineer": "distinguished-engineer";
+        "principal-engineer": "principal-engineer";
+        "senior-staff-engineer": "senior-staff-engineer";
+        "staff-engineer": "staff-engineer";
+        manager: "manager";
+        "sub-manager": "sub-manager";
+        "senior-engineer": "senior-engineer";
+        "super-senior": "super-senior";
+        "mid-level-engineer": "mid-level-engineer";
+        "junior-engineer": "junior-engineer";
+        scientist: "scientist";
+        designer: "designer";
+        "product-lead": "product-lead";
+        tester: "tester";
+        intern: "intern";
+        apprentice: "apprentice";
+    }>;
+    agentType: z.ZodString;
+    model: z.ZodString;
+    joinedAt: z.ZodNumber;
+    status: z.ZodEnum<{
+        active: "active";
+        idle: "idle";
+        working: "working";
+        blocked: "blocked";
+        completed: "completed";
+        failed: "failed";
+    }>;
+    currentTaskId: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodString;
+}, z.core.$strip>;
+export declare const teamConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    createdAt: z.ZodNumber;
+    leadAgentId: z.ZodString;
+    phase: z.ZodEnum<{
+        planning: "planning";
+        "pre-alpha": "pre-alpha";
+        alpha: "alpha";
+        beta: "beta";
+        production: "production";
+        mature: "mature";
+    }>;
+    members: z.ZodArray<z.ZodObject<{
+        agentId: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodEnum<{
+            researcher: "researcher";
+            reviewer: "reviewer";
+            coordinator: "coordinator";
+            cto: "cto";
+            "vp-engineering": "vp-engineering";
+            director: "director";
+            fellow: "fellow";
+            "distinguished-engineer": "distinguished-engineer";
+            "principal-engineer": "principal-engineer";
+            "senior-staff-engineer": "senior-staff-engineer";
+            "staff-engineer": "staff-engineer";
+            manager: "manager";
+            "sub-manager": "sub-manager";
+            "senior-engineer": "senior-engineer";
+            "super-senior": "super-senior";
+            "mid-level-engineer": "mid-level-engineer";
+            "junior-engineer": "junior-engineer";
+            scientist: "scientist";
+            designer: "designer";
+            "product-lead": "product-lead";
+            tester: "tester";
+            intern: "intern";
+            apprentice: "apprentice";
+        }>;
+        agentType: z.ZodString;
+        model: z.ZodString;
+        joinedAt: z.ZodNumber;
+        status: z.ZodEnum<{
+            active: "active";
+            idle: "idle";
+            working: "working";
+            blocked: "blocked";
+            completed: "completed";
+            failed: "failed";
+        }>;
+        currentTaskId: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodString;
+    }, z.core.$strip>>;
+    settings: z.ZodObject<{
+        maxMembers: z.ZodNumber;
+        autoAssign: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const teamTaskSchema: z.ZodObject<{
+    id: z.ZodString;
+    subject: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        completed: "completed";
+        pending: "pending";
+        in_progress: "in_progress";
+    }>;
+    owner: z.ZodOptional<z.ZodString>;
+    blockedBy: z.ZodArray<z.ZodString>;
+    blocks: z.ZodArray<z.ZodString>;
+    phase: z.ZodEnum<{
+        planning: "planning";
+        "pre-alpha": "pre-alpha";
+        alpha: "alpha";
+        beta: "beta";
+        production: "production";
+        mature: "mature";
+    }>;
+    activeForm: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const teamProtocolMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"idle_notification">;
+    from: z.ZodString;
+    timestamp: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    completedTaskId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"task_completed">;
+    from: z.ZodString;
+    taskId: z.ZodString;
+    taskSubject: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shutdown_request">;
+    requestId: z.ZodString;
+    from: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shutdown_approved">;
+    requestId: z.ZodString;
+    from: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shutdown_rejected">;
+    requestId: z.ZodString;
+    from: z.ZodString;
+    reason: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"plan_approval_request">;
+    requestId: z.ZodString;
+    from: z.ZodString;
+    planContent: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"plan_approval_response">;
+    requestId: z.ZodString;
+    approved: z.ZodBoolean;
+    feedback: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"message">;
+    from: z.ZodString;
+    to: z.ZodString;
+    text: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"broadcast">;
+    from: z.ZodString;
+    text: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>], "type">;

package/dist/common/src/types/team-config.d.ts

@@ -0,0 +1,42 @@
+export type TeamRole = 'coordinator' | 'cto' | 'vp-engineering' | 'director' | 'fellow' | 'distinguished-engineer' | 'principal-engineer' | 'senior-staff-engineer' | 'staff-engineer' | 'manager' | 'sub-manager' | 'senior-engineer' | 'super-senior' | 'mid-level-engineer' | 'junior-engineer' | 'researcher' | 'scientist' | 'designer' | 'product-lead' | 'tester' | 'reviewer' | 'intern' | 'apprentice';
+export type DevPhase = 'planning' | 'pre-alpha' | 'alpha' | 'beta' | 'production' | 'mature';
+export type AgentStatus = 'active' | 'idle' | 'working' | 'blocked' | 'completed' | 'failed';
+export interface TeamMember {
+    agentId: string;
+    name: string;
+    role: TeamRole;
+    agentType: string;
+    model: string;
+    joinedAt: number;
+    status: AgentStatus;
+    currentTaskId?: string;
+    cwd: string;
+}
+export interface TeamConfig {
+    name: string;
+    description: string;
+    createdAt: number;
+    leadAgentId: string;
+    phase: DevPhase;
+    members: TeamMember[];
+    settings: {
+        maxMembers: number;
+        autoAssign: boolean;
+    };
+}
+export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
+export interface TeamTask {
+    id: string;
+    subject: string;
+    description: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'blocked';
+    priority: TaskPriority;
+    owner?: string;
+    blockedBy: string[];
+    blocks: string[];
+    phase: DevPhase;
+    activeForm?: string;
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+}

package/dist/common/src/types/team-hook-events.d.ts

@@ -0,0 +1,36 @@
+import type { DevPhase } from './team-config';
+/**
+ * Hook event fired when an agent goes idle (no active tasks).
+ */
+export type TeammateIdleHookEvent = {
+    type: 'teammate_idle';
+    agentName: string;
+    teamName: string;
+    lastTaskId?: string;
+    timestamp: number;
+};
+/**
+ * Hook event fired when a task is marked as completed.
+ */
+export type TaskCompletedHookEvent = {
+    type: 'task_completed';
+    taskId: string;
+    taskSubject: string;
+    owner: string;
+    teamName: string;
+    timestamp: number;
+};
+/**
+ * Hook event fired when the team's dev phase changes.
+ */
+export type PhaseTransitionHookEvent = {
+    type: 'phase_transition';
+    teamName: string;
+    fromPhase: DevPhase;
+    toPhase: DevPhase;
+    timestamp: number;
+};
+/**
+ * Union of all team hook event types.
+ */
+export type TeamHookEvent = TeammateIdleHookEvent | TaskCompletedHookEvent | PhaseTransitionHookEvent;

package/dist/common/src/types/team-protocol.d.ts

@@ -0,0 +1,64 @@
+export type IdleNotification = {
+    type: 'idle_notification';
+    from: string;
+    timestamp: string;
+    summary?: string;
+    completedTaskId?: string;
+};
+export type TaskCompletedMessage = {
+    type: 'task_completed';
+    from: string;
+    taskId: string;
+    taskSubject: string;
+    timestamp: string;
+};
+export type ShutdownRequest = {
+    type: 'shutdown_request';
+    requestId: string;
+    from: string;
+    reason?: string;
+    timestamp: string;
+};
+export type ShutdownApproved = {
+    type: 'shutdown_approved';
+    requestId: string;
+    from: string;
+    timestamp: string;
+};
+export type ShutdownRejected = {
+    type: 'shutdown_rejected';
+    requestId: string;
+    from: string;
+    reason: string;
+    timestamp: string;
+};
+export type PlanApprovalRequest = {
+    type: 'plan_approval_request';
+    requestId: string;
+    from: string;
+    planContent: string;
+    timestamp: string;
+};
+export type PlanApprovalResponse = {
+    type: 'plan_approval_response';
+    requestId: string;
+    approved: boolean;
+    feedback?: string;
+    timestamp: string;
+};
+export type TeamMessage = {
+    type: 'message';
+    from: string;
+    to: string;
+    text: string;
+    summary?: string;
+    timestamp: string;
+};
+export type BroadcastMessage = {
+    type: 'broadcast';
+    from: string;
+    text: string;
+    summary?: string;
+    timestamp: string;
+};
+export type TeamProtocolMessage = IdleNotification | TaskCompletedMessage | ShutdownRequest | ShutdownApproved | ShutdownRejected | PlanApprovalRequest | PlanApprovalResponse | TeamMessage | BroadcastMessage;

package/dist/common/src/util/agent-id-parsing.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Parse agent ID to extract publisher, agent name, and version
+ * Supports formats:
+ * - publisher/agentId[@version]
+ * - agentId[@version] (no publisher)
+ */
+export declare function parseAgentId(fullAgentId: string): {
+    publisherId?: string;
+    agentId?: string;
+    version?: string;
+    givenAgentId: string;
+};
+/**
+ * Parse published agent ID to extract publisher, agent name, and optionally version
+ *
+ * If the agent ID is not in the publisher/agent format, return null
+ */
+export declare function parsePublishedAgentId(fullAgentId: string): {
+    publisherId: string;
+    agentId: string;
+    version?: string;
+} | null;

package/dist/common/src/util/agent-name-normalization.d.ts

@@ -0,0 +1,12 @@
+export declare const DEFAULT_ORG_PREFIX = "levelcode/";
+/**
+ * Resolves an agent ID by trying multiple strategies:
+ * 1. Direct lookup in registry
+ * 2. Try with DEFAULT_ORG_PREFIX for spawnable agents
+ * 3. Return null if not found
+ *
+ * This provides a more robust alternative to string concatenation
+ * and handles the common case where users reference spawnable agents
+ * without the org prefix.
+ */
+export declare function resolveAgentId(agentId: string, agentRegistry: Record<string, any>): string | null;

package/dist/common/src/util/array.d.ts

@@ -0,0 +1,6 @@
+export declare function filterDefined<T>(array: (T | null | undefined)[]): T[];
+type Falsey = false | undefined | null | 0 | '';
+type FalseyValueArray<T> = T | Falsey | FalseyValueArray<T>[];
+export declare function buildArray<T>(...params: FalseyValueArray<T>[]): T[];
+export declare function groupConsecutive<T, U>(xs: T[], key: (x: T) => U): any[];
+export {};

package/dist/common/src/util/credentials.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod/v4';
+export declare const userSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    authToken: z.ZodString;
+    fingerprintId: z.ZodString;
+    fingerprintHash: z.ZodString;
+}, z.core.$strip>;
+export type User = z.infer<typeof userSchema>;
+export declare const genAuthCode: (fingerprintId: string, expiresAt: string, secret: string) => string;

package/dist/common/src/util/error.d.ts

@@ -0,0 +1,128 @@
+export type ErrorOr<T, E extends ErrorObject = ErrorObject> = Success<T> | Failure<E>;
+export type Success<T> = {
+    success: true;
+    value: T;
+};
+export type Failure<E extends ErrorObject = ErrorObject> = {
+    success: false;
+    error: E;
+};
+/**
+ * Result type for prompt functions that can be aborted.
+ * Provides rich semantics to distinguish between successful completion and user abort.
+ *
+ * ## When to use `PromptResult<T>` vs `ErrorOr<T>`
+ *
+ * Use `PromptResult<T>` when:
+ * - The operation can be cancelled by the user (via AbortSignal)
+ * - An abort is an expected outcome, not an error
+ * - You need to distinguish between errors (which might trigger fallbacks) and
+ *   user-initiated aborts (which should propagate immediately)
+ *
+ * Use `ErrorOr<T>` when:
+ * - The operation can fail with an error that should be handled
+ * - There's no concept of user-initiated abort
+ * - You want to return error details rather than throw
+ *
+ * ## Abort handling patterns
+ *
+ * 1. **Check and return early** - For graceful handling where abort means "stop, no error":
+ *    ```ts
+ *    const result = await promptAiSdk({ ... })
+ *    if (result.aborted) return // or return null, false, etc.
+ *    doSomething(result.value)
+ *    ```
+ *
+ * 2. **Unwrap and throw** - For propagating aborts as exceptions:
+ *    ```ts
+ *    const value = unwrapPromptResult(await promptAiSdk({ ... }))
+ *    // Throws if aborted, callers should use isAbortError() in catch blocks
+ *    ```
+ *
+ * 3. **Rethrow in catch blocks** - Prevent swallowing abort errors:
+ *    ```ts
+ *    try {
+ *      await someOperation()
+ *    } catch (error) {
+ *      if (isAbortError(error)) throw error // Don't swallow aborts
+ *      // Handle other errors
+ *    }
+ *    ```
+ */
+export type PromptResult<T> = PromptSuccess<T> | PromptAborted;
+export type PromptSuccess<T> = {
+    aborted: false;
+    value: T;
+};
+export type PromptAborted = {
+    aborted: true;
+    reason?: string;
+};
+export type ErrorObject = {
+    name: string;
+    message: string;
+    stack?: string;
+    /** HTTP status code from error.status (used by some libraries) */
+    status?: number;
+    /** HTTP status code from error.statusCode (used by AI SDK and LevelCode errors) */
+    statusCode?: number;
+    /** Optional machine-friendly error code, if available */
+    code?: string;
+    /** Optional raw error object */
+    rawError?: string;
+    /** Response body from API errors (AI SDK APICallError) */
+    responseBody?: string;
+    /** URL that was called (API errors) */
+    url?: string;
+    /** Whether the error is retryable (API errors) */
+    isRetryable?: boolean;
+    /** Request body values that were sent (API errors) - stringified for safety */
+    requestBodyValues?: string;
+    /** Cause of the error, if nested */
+    cause?: ErrorObject;
+};
+export declare function success<T>(value: T): Success<T>;
+export declare function failure(error: unknown): Failure<ErrorObject>;
+/**
+ * Create a successful prompt result.
+ */
+export declare function promptSuccess<T>(value: T): PromptSuccess<T>;
+/**
+ * Create an aborted prompt result.
+ */
+export declare function promptAborted(reason?: string): PromptAborted;
+/**
+ * Standard error message for aborted requests.
+ * Use this constant when throwing abort errors to ensure consistency.
+ */
+export declare const ABORT_ERROR_MESSAGE = "Request aborted";
+/**
+ * Custom error class for abort errors.
+ * Use this class instead of generic Error for abort errors to ensure
+ * robust detection via isAbortError() (checks error.name === 'AbortError').
+ */
+export declare class AbortError extends Error {
+    constructor(reason?: string);
+}
+/**
+ * Check if an error is an abort error.
+ * Use this helper to detect abort errors in catch blocks.
+ *
+ * Detects both:
+ * - Errors with message starting with 'Request aborted' (thrown by our code via AbortError)
+ * - Native AbortError (thrown by fetch/AI SDK when AbortSignal is triggered)
+ */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * Unwrap a PromptResult, returning the value if successful or throwing if aborted.
+ *
+ * Use this helper for consistent abort handling when you want aborts to propagate
+ * as exceptions. Callers should use `isAbortError()` in catch blocks to detect
+ * and handle abort errors appropriately (e.g., rethrow instead of logging as errors).
+ *
+ * @throws {AbortError} When result.aborted is true.
+ */
+export declare function unwrapPromptResult<T>(result: PromptResult<T>): T;
+export declare function getErrorObject(error: unknown, options?: {
+    includeRawError?: boolean;
+}): ErrorObject;