@tangle-network/agent-interface 0.4.0 → 0.5.0

package/dist/agent-profile.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Provider-neutral agent profile types for public SDK consumers.
+ *
+ * These model portable agent intent at the application boundary. Individual
+ * backends translate this shape into their own native profile/configuration
+ * formats internally. This is the canonical home; `@tangle-network/sandbox`
+ * re-exports these symbols for backward compatibility.
+ */
+/**
+ * Permission policy value for a capability.
+ */
+export type AgentProfilePermissionValue = "allow" | "ask" | "deny";
+export type AgentProfilePermission = AgentProfilePermissionValue | Record<string, AgentProfilePermissionValue>;
+/**
+ * Generic resource reference that can be resolved into a file or instruction.
+ */
+export type AgentProfileResourceRef = {
+    kind: "inline";
+    name: string;
+    content: string;
+} | {
+    kind: "github";
+    /**
+     * Optional repository in "owner/repo" form. When omitted, providers may
+     * only resolve the path if they have an ambient repository context.
+     */
+    repository?: string;
+    path: string;
+    ref?: string;
+    name?: string;
+};
+/**
+ * Helper for creating typed inline resource refs.
+ */
+export declare function defineInlineResource(name: string, content: string): AgentProfileResourceRef;
+/**
+ * Helper for creating typed GitHub-backed resource refs.
+ */
+export declare function defineGitHubResource(path: string, options?: {
+    repository?: string;
+    ref?: string;
+    name?: string;
+}): AgentProfileResourceRef;
+/**
+ * Resource mounted into a backend workspace.
+ */
+export interface AgentProfileFileMount {
+    path: string;
+    resource: AgentProfileResourceRef;
+    executable?: boolean;
+}
+/**
+ * Provider-neutral resource bundle.
+ */
+export interface AgentProfileResources {
+    /**
+     * Generic files to materialize into the agent workspace before execution.
+     */
+    files?: AgentProfileFileMount[];
+    /**
+     * Provider-native tool files. Backends materialize these into their standard
+     * discovery location when they support file-based tools.
+     */
+    tools?: AgentProfileResourceRef[];
+    /**
+     * Agent Skills (`SKILL.md`) packages. Supported by Cursor, Claude Code,
+     * Codex-compatible layouts, OpenCode, and Hermes-style skill harnesses.
+     */
+    skills?: AgentProfileResourceRef[];
+    /**
+     * Provider-native subagent definition files.
+     */
+    agents?: AgentProfileResourceRef[];
+    /**
+     * Provider-native slash command files.
+     */
+    commands?: AgentProfileResourceRef[];
+    /**
+     * Additional instructions injected into the agent context.
+     */
+    instructions?: string | AgentProfileResourceRef;
+    /**
+     * Fail initialization when a provider cannot materialize a resource.
+     */
+    failOnError?: boolean;
+}
+/**
+ * Model selection hints for backends.
+ */
+export interface AgentProfileModelHints {
+    /**
+     * Preferred default model (format depends on backend, commonly "provider/model").
+     */
+    default?: string;
+    /**
+     * Preferred small/cheap model for lightweight work.
+     */
+    small?: string;
+    /**
+     * Optional provider preference hint.
+     */
+    provider?: string;
+    /**
+     * Backend-agnostic model metadata/hints.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Prompt shaping for an agent.
+ */
+export interface AgentProfilePrompt {
+    /**
+     * Full system prompt replacement, when supported.
+     */
+    systemPrompt?: string;
+    /**
+     * Additional instruction lines appended to the active prompt.
+     */
+    instructions?: string[];
+}
+/**
+ * Generic subagent definition.
+ */
+export interface AgentSubagentProfile {
+    description?: string;
+    prompt?: string;
+    model?: string;
+    tools?: Record<string, boolean>;
+    permissions?: Record<string, AgentProfilePermission>;
+    maxSteps?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentProfileHookCommand {
+    command: string;
+    timeoutMs?: number;
+    blocking?: boolean;
+    matcher?: string;
+    env?: Record<string, string>;
+}
+export interface AgentProfileMode {
+    description?: string;
+    model?: string;
+    prompt?: string;
+    tools?: Record<string, boolean>;
+    permissions?: Record<string, AgentProfilePermission>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Confidential-execution options for sandbox backends.
+ *
+ * The Tangle blueprint path translates this into TEE job parameters and fails
+ * closed when the requested TEE is unavailable. Callers should verify returned
+ * attestation evidence before treating a session as confidential.
+ */
+export interface AgentProfileConfidential {
+    /**
+     * TEE variant requested from the operator.
+     */
+    tee?: "tdx" | "nitro" | "phala-dstack" | "sev-snp" | "any" | (string & {});
+    /**
+     * Optional hex-encoded 32-64 byte challenge for deploy-time report data.
+     */
+    attestationNonce?: string;
+    /**
+     * Require no persistence across session end when supported by the backend.
+     */
+    sealed?: boolean;
+    /**
+     * Ask the SDK/backend to create or require a fresh attestation challenge.
+     */
+    attestationRefresh?: boolean;
+}
+/**
+ * Generic MCP server configuration.
+ */
+export interface AgentProfileMcpServer {
+    transport?: "stdio" | "sse" | "http";
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    enabled?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Public provider-neutral agent profile contract.
+ */
+export interface AgentProfile {
+    name?: string;
+    description?: string;
+    version?: string;
+    tags?: string[];
+    prompt?: AgentProfilePrompt;
+    model?: AgentProfileModelHints;
+    permissions?: Record<string, AgentProfilePermission>;
+    tools?: Record<string, boolean>;
+    mcp?: Record<string, AgentProfileMcpServer>;
+    subagents?: Record<string, AgentSubagentProfile>;
+    resources?: AgentProfileResources;
+    hooks?: Record<string, AgentProfileHookCommand[]>;
+    modes?: Record<string, AgentProfileMode>;
+    confidential?: AgentProfileConfidential;
+    metadata?: Record<string, unknown>;
+    /**
+     * Non-portable backend-specific extensions.
+     *
+     * Use this only for features that cannot be expressed generically.
+     * SDK consumers should treat extension keys as backend namespaces.
+     */
+    extensions?: Record<string, Record<string, unknown> | undefined>;
+}
+/**
+ * Helper for declaring typed profiles in application code.
+ */
+export declare function defineAgentProfile<T extends AgentProfile>(profile: T): T;
+/**
+ * Capabilities describing how a backend interprets AgentProfile.
+ */
+export interface AgentProfileCapabilities {
+    namedProfiles: boolean;
+    systemPrompt: boolean;
+    instructions: boolean;
+    tools: boolean;
+    permissions: boolean;
+    mcp: boolean;
+    subagents: boolean;
+    resources: {
+        files: boolean;
+        instructions: boolean;
+        tools?: boolean;
+        skills?: boolean;
+        agents?: boolean;
+        commands?: boolean;
+    };
+    hooks?: boolean;
+    modes?: boolean;
+    runtimeUpdate: boolean;
+    validation: boolean;
+    /**
+     * Backend extension namespaces understood by this backend.
+     */
+    extensions?: string[];
+}
+/**
+ * Validation issue for a profile/backend pairing.
+ */
+export interface AgentProfileValidationIssue {
+    level: "error" | "warning" | "info";
+    code: string;
+    message: string;
+    path?: string;
+}
+/**
+ * Validation output for a provider adapter.
+ */
+export interface AgentProfileValidationResult {
+    ok: boolean;
+    issues: AgentProfileValidationIssue[];
+    normalizedProfile?: AgentProfile;
+}
+/**
+ * Merge two public AgentProfile values.
+ *
+ * Overlay fields win on conflicts. Array-like instruction sets are appended.
+ */
+export declare function mergeAgentProfiles(base: AgentProfile | undefined, overlay: AgentProfile | undefined): AgentProfile | undefined;

package/dist/agent-profile.js

@@ -0,0 +1,102 @@
+/**
+ * Provider-neutral agent profile types for public SDK consumers.
+ *
+ * These model portable agent intent at the application boundary. Individual
+ * backends translate this shape into their own native profile/configuration
+ * formats internally. This is the canonical home; `@tangle-network/sandbox`
+ * re-exports these symbols for backward compatibility.
+ */
+/**
+ * Helper for creating typed inline resource refs.
+ */
+export function defineInlineResource(name, content) {
+    return { kind: "inline", name, content };
+}
+/**
+ * Helper for creating typed GitHub-backed resource refs.
+ */
+export function defineGitHubResource(path, options = {}) {
+    return {
+        kind: "github",
+        repository: options.repository,
+        path,
+        ref: options.ref,
+        name: options.name,
+    };
+}
+/**
+ * Helper for declaring typed profiles in application code.
+ */
+export function defineAgentProfile(profile) {
+    return profile;
+}
+function mergeStringArrays(base, overlay) {
+    if (!base && !overlay)
+        return undefined;
+    return [...(base ?? []), ...(overlay ?? [])];
+}
+function mergeRecord(base, overlay) {
+    if (!base && !overlay)
+        return undefined;
+    return {
+        ...(base ?? {}),
+        ...(overlay ?? {}),
+    };
+}
+/**
+ * Merge two public AgentProfile values.
+ *
+ * Overlay fields win on conflicts. Array-like instruction sets are appended.
+ */
+export function mergeAgentProfiles(base, overlay) {
+    if (!base && !overlay)
+        return undefined;
+    const mergedPrompt = base?.prompt || overlay?.prompt
+        ? {
+            ...(base?.prompt ?? {}),
+            ...(overlay?.prompt ?? {}),
+            instructions: mergeStringArrays(base?.prompt?.instructions, overlay?.prompt?.instructions),
+        }
+        : undefined;
+    const mergedResources = base?.resources || overlay?.resources
+        ? {
+            ...(base?.resources ?? {}),
+            ...(overlay?.resources ?? {}),
+            files: [
+                ...(base?.resources?.files ?? []),
+                ...(overlay?.resources?.files ?? []),
+            ],
+            tools: [
+                ...(base?.resources?.tools ?? []),
+                ...(overlay?.resources?.tools ?? []),
+            ],
+            skills: [
+                ...(base?.resources?.skills ?? []),
+                ...(overlay?.resources?.skills ?? []),
+            ],
+            agents: [
+                ...(base?.resources?.agents ?? []),
+                ...(overlay?.resources?.agents ?? []),
+            ],
+            commands: [
+                ...(base?.resources?.commands ?? []),
+                ...(overlay?.resources?.commands ?? []),
+            ],
+            instructions: overlay?.resources?.instructions ?? base?.resources?.instructions,
+        }
+        : undefined;
+    return {
+        ...(base ?? {}),
+        ...(overlay ?? {}),
+        prompt: mergedPrompt,
+        permissions: mergeRecord(base?.permissions, overlay?.permissions),
+        tools: mergeRecord(base?.tools, overlay?.tools),
+        mcp: mergeRecord(base?.mcp, overlay?.mcp),
+        subagents: mergeRecord(base?.subagents, overlay?.subagents),
+        resources: mergedResources,
+        hooks: mergeRecord(base?.hooks, overlay?.hooks),
+        modes: mergeRecord(base?.modes, overlay?.modes),
+        metadata: mergeRecord(base?.metadata, overlay?.metadata),
+        extensions: mergeRecord(base?.extensions, overlay?.extensions),
+    };
+}

package/dist/index.d.ts

@@ -578,4 +578,5 @@ export interface SdkProviderAdapter {
     downloadArtifact?(sessionId: string, path: string): Promise<Uint8Array>;
     submitQuestionAnswer?(answers: Record<string, string[]>): Promise<void>;
 }
+export * from "./agent-profile.js";
 export * from "./profile-schema.js";

package/dist/index.js

@@ -122,4 +122,5 @@ export function resolveNativeWebTools(tools) {
     }
     return posture;
 }
+export * from "./agent-profile.js";
 export * from "./profile-schema.js";

package/dist/profile-schema.d.ts

@@ -1,33 +1,22 @@
 import { z } from "zod";
 export declare const agentProfilePermissionValueSchema: z.ZodEnum<{
     allow: "allow";
-    deny: "deny";
     ask: "ask";
+    deny: "deny";
 }>;
 export declare const agentProfilePermissionSchema: z.ZodUnion<readonly [z.ZodEnum<{
     allow: "allow";
-    deny: "deny";
     ask: "ask";
+    deny: "deny";
 }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
     allow: "allow";
-    deny: "deny";
     ask: "ask";
+    deny: "deny";
 }>>]>;
 export declare const agentProfileResourceRefSchema: z.ZodUnion<readonly [z.ZodObject<{
-    content: z.ZodString;
-    name: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"inline">;
-    content: z.ZodString;
     name: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    npm: z.ZodString;
-    name: z.ZodOptional<z.ZodString>;
-    version: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    github: z.ZodString;
-    ref: z.ZodOptional<z.ZodString>;
-    name: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"github">;
     repository: z.ZodOptional<z.ZodString>;
@@ -38,20 +27,9 @@ export declare const agentProfileResourceRefSchema: z.ZodUnion<readonly [z.ZodOb
 export declare const agentProfileFileMountSchema: z.ZodObject<{
     path: z.ZodString;
     resource: z.ZodUnion<readonly [z.ZodObject<{
-        content: z.ZodString;
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"inline">;
-        content: z.ZodString;
         name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        npm: z.ZodString;
-        name: z.ZodOptional<z.ZodString>;
-        version: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        github: z.ZodString;
-        ref: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"github">;
         repository: z.ZodOptional<z.ZodString>;
@@ -61,22 +39,26 @@ export declare const agentProfileFileMountSchema: z.ZodObject<{
     }, z.core.$strip>]>;
     executable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
-export declare const agentProfileResourcesSchema: z.ZodOptional<z.ZodObject<{
+export declare const agentProfileResourcesSchema: z.ZodObject<{
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        resource: z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"inline">;
+            name: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            repository: z.ZodOptional<z.ZodString>;
+            path: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>;
+        executable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
     tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        content: z.ZodString;
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"inline">;
-        content: z.ZodString;
         name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        npm: z.ZodString;
-        name: z.ZodOptional<z.ZodString>;
-        version: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        github: z.ZodString;
-        ref: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"github">;
         repository: z.ZodOptional<z.ZodString>;
@@ -85,20 +67,9 @@ export declare const agentProfileResourcesSchema: z.ZodOptional<z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>]>>>;
     skills: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        content: z.ZodString;
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"inline">;
-        content: z.ZodString;
         name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        npm: z.ZodString;
-        name: z.ZodOptional<z.ZodString>;
-        version: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        github: z.ZodString;
-        ref: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"github">;
         repository: z.ZodOptional<z.ZodString>;
@@ -107,20 +78,9 @@ export declare const agentProfileResourcesSchema: z.ZodOptional<z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>]>>>;
     agents: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        content: z.ZodString;
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"inline">;
-        content: z.ZodString;
         name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        npm: z.ZodString;
-        name: z.ZodOptional<z.ZodString>;
-        version: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        github: z.ZodString;
-        ref: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"github">;
         repository: z.ZodOptional<z.ZodString>;
@@ -129,20 +89,9 @@ export declare const agentProfileResourcesSchema: z.ZodOptional<z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>]>>>;
     commands: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        content: z.ZodString;
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"inline">;
-        content: z.ZodString;
         name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        npm: z.ZodString;
-        name: z.ZodOptional<z.ZodString>;
-        version: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        github: z.ZodString;
-        ref: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"github">;
         repository: z.ZodOptional<z.ZodString>;
@@ -150,47 +99,10 @@ export declare const agentProfileResourcesSchema: z.ZodOptional<z.ZodObject<{
         ref: z.ZodOptional<z.ZodString>;
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>]>>>;
-    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        path: z.ZodString;
-        resource: z.ZodUnion<readonly [z.ZodObject<{
-            content: z.ZodString;
-            name: z.ZodString;
-        }, z.core.$strip>, z.ZodObject<{
-            kind: z.ZodLiteral<"inline">;
-            content: z.ZodString;
-            name: z.ZodString;
-        }, z.core.$strip>, z.ZodObject<{
-            npm: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-            version: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
-            github: z.ZodString;
-            ref: z.ZodOptional<z.ZodString>;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
-            kind: z.ZodLiteral<"github">;
-            repository: z.ZodOptional<z.ZodString>;
-            path: z.ZodString;
-            ref: z.ZodOptional<z.ZodString>;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>]>;
-        executable: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strip>>>;
     instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
-        content: z.ZodString;
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"inline">;
-        content: z.ZodString;
         name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        npm: z.ZodString;
-        name: z.ZodOptional<z.ZodString>;
-        version: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        github: z.ZodString;
-        ref: z.ZodOptional<z.ZodString>;
-        name: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"github">;
         repository: z.ZodOptional<z.ZodString>;
@@ -199,14 +111,41 @@ export declare const agentProfileResourcesSchema: z.ZodOptional<z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>]>]>>;
     failOnError: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const agentProfileModelHintsSchema: z.ZodObject<{
+    default: z.ZodOptional<z.ZodString>;
+    small: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const agentProfilePromptSchema: z.ZodObject<{
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const agentSubagentProfileSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+        deny: "deny";
+    }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+        deny: "deny";
+    }>>]>>>;
+    maxSteps: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
 export declare const agentProfileHookCommandSchema: z.ZodObject<{
     command: z.ZodString;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     blocking: z.ZodOptional<z.ZodBoolean>;
     matcher: z.ZodOptional<z.ZodString>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-}, z.core.$loose>;
+}, z.core.$strip>;
 export declare const agentProfileModeSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
@@ -214,12 +153,200 @@ export declare const agentProfileModeSchema: z.ZodObject<{
     tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
     permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
         allow: "allow";
-        deny: "deny";
         ask: "ask";
+        deny: "deny";
     }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
         allow: "allow";
+        ask: "ask";
+        deny: "deny";
+    }>>]>>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const agentProfileConfidentialSchema: z.ZodObject<{
+    tee: z.ZodOptional<z.ZodString>;
+    attestationNonce: z.ZodOptional<z.ZodString>;
+    sealed: z.ZodOptional<z.ZodBoolean>;
+    attestationRefresh: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const agentProfileMcpServerSchema: z.ZodObject<{
+    transport: z.ZodOptional<z.ZodEnum<{
+        stdio: "stdio";
+        sse: "sse";
+        http: "http";
+    }>>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * The complete provider-neutral agent profile schema — the runtime validator for
+ * the canonical {@link AgentProfile} TS contract. Kept structurally in lock-step
+ * with that interface by the compile-time guard at the bottom of this file.
+ */
+export declare const agentProfileSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    prompt: z.ZodOptional<z.ZodObject<{
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    model: z.ZodOptional<z.ZodObject<{
+        default: z.ZodOptional<z.ZodString>;
+        small: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
         deny: "deny";
+    }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
+        allow: "allow";
         ask: "ask";
+        deny: "deny";
     }>>]>>>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    mcp: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        transport: z.ZodOptional<z.ZodEnum<{
+            stdio: "stdio";
+            sse: "sse";
+            http: "http";
+        }>>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    subagents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+        permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
+            allow: "allow";
+            ask: "ask";
+            deny: "deny";
+        }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
+            allow: "allow";
+            ask: "ask";
+            deny: "deny";
+        }>>]>>>;
+        maxSteps: z.ZodOptional<z.ZodNumber>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    resources: z.ZodOptional<z.ZodObject<{
+        files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            resource: z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>;
+            executable: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"inline">;
+            name: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            repository: z.ZodOptional<z.ZodString>;
+            path: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"inline">;
+            name: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            repository: z.ZodOptional<z.ZodString>;
+            path: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>>;
+        agents: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"inline">;
+            name: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            repository: z.ZodOptional<z.ZodString>;
+            path: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>>;
+        commands: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"inline">;
+            name: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            repository: z.ZodOptional<z.ZodString>;
+            path: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>>;
+        instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"inline">;
+            name: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"github">;
+            repository: z.ZodOptional<z.ZodString>;
+            path: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>]>>;
+        failOnError: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    hooks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        blocking: z.ZodOptional<z.ZodBoolean>;
+        matcher: z.ZodOptional<z.ZodString>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>>>;
+    modes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodOptional<z.ZodString>;
+        tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+        permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
+            allow: "allow";
+            ask: "ask";
+            deny: "deny";
+        }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
+            allow: "allow";
+            ask: "ask";
+            deny: "deny";
+        }>>]>>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    confidential: z.ZodOptional<z.ZodObject<{
+        tee: z.ZodOptional<z.ZodString>;
+        attestationNonce: z.ZodOptional<z.ZodString>;
+        sealed: z.ZodOptional<z.ZodBoolean>;
+        attestationRefresh: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$loose>;
+    extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodUndefined]>>>;
+}, z.core.$strip>;

package/dist/profile-schema.js

@@ -1,32 +1,15 @@
 import { z } from "zod";
-export const agentProfilePermissionValueSchema = z.enum([
-    "allow",
-    "deny",
-    "ask",
-]);
+export const agentProfilePermissionValueSchema = z.enum(["allow", "deny", "ask"]);
 export const agentProfilePermissionSchema = z.union([
     agentProfilePermissionValueSchema,
     z.record(z.string(), agentProfilePermissionValueSchema),
 ]);
+// Mirrors the canonical AgentProfileResourceRef (inline | github), kind-discriminated.
 export const agentProfileResourceRefSchema = z.union([
-    z.object({
-        content: z.string(),
-        name: z.string(),
-    }),
     z.object({
         kind: z.literal("inline"),
-        content: z.string(),
         name: z.string(),
-    }),
-    z.object({
-        npm: z.string(),
-        name: z.string().optional(),
-        version: z.string().optional(),
-    }),
-    z.object({
-        github: z.string(),
-        ref: z.string().optional(),
-        name: z.string().optional(),
+        content: z.string(),
     }),
     z.object({
         kind: z.literal("github"),
@@ -41,35 +24,90 @@ export const agentProfileFileMountSchema = z.object({
     resource: agentProfileResourceRefSchema,
     executable: z.boolean().optional(),
 });
-export const agentProfileResourcesSchema = z
-    .object({
+export const agentProfileResourcesSchema = z.object({
+    files: z.array(agentProfileFileMountSchema).optional(),
     tools: z.array(agentProfileResourceRefSchema).optional(),
     skills: z.array(agentProfileResourceRefSchema).optional(),
     agents: z.array(agentProfileResourceRefSchema).optional(),
     commands: z.array(agentProfileResourceRefSchema).optional(),
-    files: z.array(agentProfileFileMountSchema).optional(),
-    instructions: z
-        .union([z.string(), agentProfileResourceRefSchema])
-        .optional(),
+    instructions: z.union([z.string(), agentProfileResourceRefSchema]).optional(),
     failOnError: z.boolean().optional(),
-})
-    .optional();
-export const agentProfileHookCommandSchema = z
-    .object({
+});
+export const agentProfileModelHintsSchema = z.object({
+    default: z.string().optional(),
+    small: z.string().optional(),
+    provider: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const agentProfilePromptSchema = z.object({
+    systemPrompt: z.string().optional(),
+    instructions: z.array(z.string()).optional(),
+});
+export const agentSubagentProfileSchema = z.object({
+    description: z.string().optional(),
+    prompt: z.string().optional(),
+    model: z.string().optional(),
+    tools: z.record(z.string(), z.boolean()).optional(),
+    permissions: z.record(z.string(), agentProfilePermissionSchema).optional(),
+    maxSteps: z.number().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const agentProfileHookCommandSchema = z.object({
     command: z.string(),
     timeoutMs: z.number().positive().optional(),
     blocking: z.boolean().optional(),
     matcher: z.string().optional(),
     env: z.record(z.string(), z.string()).optional(),
-})
-    .passthrough();
-export const agentProfileModeSchema = z
-    .object({
+});
+export const agentProfileModeSchema = z.object({
     description: z.string().optional(),
     model: z.string().optional(),
     prompt: z.string().optional(),
     tools: z.record(z.string(), z.boolean()).optional(),
     permissions: z.record(z.string(), agentProfilePermissionSchema).optional(),
     metadata: z.record(z.string(), z.unknown()).optional(),
-})
-    .passthrough();
+});
+export const agentProfileConfidentialSchema = z.object({
+    tee: z.string().optional(),
+    attestationNonce: z.string().optional(),
+    sealed: z.boolean().optional(),
+    attestationRefresh: z.boolean().optional(),
+});
+export const agentProfileMcpServerSchema = z.object({
+    transport: z.enum(["stdio", "sse", "http"]).optional(),
+    command: z.string().optional(),
+    args: z.array(z.string()).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    cwd: z.string().optional(),
+    url: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    enabled: z.boolean().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * The complete provider-neutral agent profile schema — the runtime validator for
+ * the canonical {@link AgentProfile} TS contract. Kept structurally in lock-step
+ * with that interface by the compile-time guard at the bottom of this file.
+ */
+export const agentProfileSchema = z.object({
+    name: z.string().optional(),
+    description: z.string().optional(),
+    version: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    prompt: agentProfilePromptSchema.optional(),
+    model: agentProfileModelHintsSchema.optional(),
+    permissions: z.record(z.string(), agentProfilePermissionSchema).optional(),
+    tools: z.record(z.string(), z.boolean()).optional(),
+    mcp: z.record(z.string(), agentProfileMcpServerSchema).optional(),
+    subagents: z.record(z.string(), agentSubagentProfileSchema).optional(),
+    resources: agentProfileResourcesSchema.optional(),
+    hooks: z.record(z.string(), z.array(agentProfileHookCommandSchema)).optional(),
+    modes: z.record(z.string(), agentProfileModeSchema).optional(),
+    confidential: agentProfileConfidentialSchema.optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    extensions: z
+        .record(z.string(), z.union([z.record(z.string(), z.unknown()), z.undefined()]))
+        .optional(),
+});
+const _agentProfileSchemaMatchesInterface = true;
+void _agentProfileSchemaMatchesInterface;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",