@xenosystem/agent-sdk 0.8.12

package/dist/skills/index.d.ts

@@ -0,0 +1,277 @@
+interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean | Record<string, unknown>;
+        [keyword: string]: unknown;
+    };
+}
+interface ImageUrlBlock {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+}
+interface ResourceContentBlock {
+    type: "resource";
+    uri?: string;
+    mimeType?: string;
+    text?: string;
+    data?: string;
+}
+type ToolAssistantContentBlock = TextBlock | ImageUrlBlock | ResourceContentBlock;
+type ToolOperationState = "registered" | "starting" | "running_foreground" | "running_background" | "waiting_for_input" | "stalled" | "verifying" | "completed" | "failed" | "timed_out" | "cancelled" | "orphaned";
+type ToolCompletionPolicy = "await" | "observe" | "detach";
+interface ExpectedOutputContract {
+    path: string;
+    kind?: "file" | "directory";
+    nonEmpty?: boolean;
+}
+interface ToolEvidence {
+    id: string;
+    kind: "artifact" | "process" | "verification";
+    status: "pending" | "verified" | "failed";
+    path?: string;
+    observedAt: string;
+    operationId: string;
+    detail?: Record<string, string | number | boolean | null>;
+}
+interface ToolOperationSnapshot {
+    schemaVersion: 1;
+    operationId: string;
+    turnId: string;
+    generation: number;
+    toolCallId: string;
+    toolName: string;
+    ownerSessionId?: string;
+    state: ToolOperationState;
+    terminal: boolean;
+    presentation: "foreground" | "background";
+    completionPolicy: ToolCompletionPolicy;
+    promotable: boolean;
+    processId?: string;
+    taskId?: string;
+    pid?: number;
+    commandFingerprint?: string;
+    outputPath?: string;
+    startedAt: string;
+    lastActivityAt: string;
+    deadlineAt?: string;
+    elapsedMs: number;
+    idleMs: number;
+    outputBytes: number;
+    nextOffset: number;
+    exitCode?: number | null;
+    completionReason?: string;
+    suggestedNextAction?: string;
+    expectedOutputs?: ExpectedOutputContract[];
+    evidence?: ToolEvidence[];
+}
+interface ToolProgressUpdate {
+    activity?: "stdout" | "stderr" | "input" | "waiting_for_input" | "heartbeat" | "state";
+    message?: string;
+    bytes?: number;
+    outputBytes?: number;
+    nextOffset?: number;
+}
+interface ToolAuthorizationReceipt {
+    turnId: string;
+    toolCallId: string;
+    toolName: string;
+    iteration: number;
+    policy: {
+        allowed: true;
+        reason: string;
+        temporaryOverride: boolean;
+    };
+    permission: {
+        allowed: true;
+        reason: string;
+    };
+}
+interface ToolResult {
+    success: boolean;
+    output: string;
+    error?: string;
+    errorCode?: string;
+    errorDetails?: Record<string, unknown>;
+    assistantContent?: ToolAssistantContentBlock[];
+    assistantOnlyContent?: ToolAssistantContentBlock[];
+    operation?: ToolOperationSnapshot;
+    evidence?: ToolEvidence[];
+    retryable?: boolean;
+}
+interface ToolExecutionContext {
+    signal?: AbortSignal;
+    operationId?: string;
+    reportProgress?: (event: ToolProgressUpdate) => void;
+    authorization?: ToolAuthorizationReceipt;
+}
+type ToolExecutor = (input: Record<string, unknown>, context?: ToolExecutionContext) => Promise<ToolResult>;
+interface ToolPolicyProjection {
+    observabilityInput: Record<string, unknown>;
+    permissionInput: Record<string, unknown>;
+    permissionPreview?: string;
+    approvalKey?: string;
+    riskLevel?: "low" | "medium" | "high";
+}
+interface RegisteredTool {
+    definition: ToolDefinition;
+    execute: ToolExecutor;
+    projectPolicyInput?: (input: Record<string, unknown>) => ToolPolicyProjection | {
+        error: ToolResult;
+    };
+}
+interface TextBlock {
+    type: "text";
+    text: string;
+}
+declare const XENO_SKILL_SCHEMA_VERSION: 2;
+type XenoSkillSource = "managed" | "built-in" | "user" | "project" | "plugin" | "compatible" | "legacy";
+type XenoSkillExternalActionPolicy = "deny" | "ask" | "allow";
+type XenoSkillInvocationDecision = "allow" | "ask" | "deny";
+interface XenoSkillDiscoveryRoot {
+    path: string;
+    source: XenoSkillSource;
+    precedence: number;
+    namespace?: string;
+    followSymlinks?: boolean;
+}
+interface XenoSkillResourceDescriptor {
+    relativePath: string;
+    kind: "script" | "reference" | "asset" | "template" | "other";
+    sizeBytes: number;
+    sha256: string;
+}
+interface XenoSkillToolPolicy {
+    allow?: string[];
+    deny?: string[];
+}
+interface XenoSkillDescriptor {
+    schemaVersion: typeof XENO_SKILL_SCHEMA_VERSION;
+    key: string;
+    name: string;
+    description: string;
+    source: XenoSkillSource;
+    precedence: number;
+    directory: string;
+    entrypoint: string;
+    namespace?: string;
+    version?: string;
+    license?: string;
+    compatibility?: string;
+    metadata: Record<string, string>;
+    modelInvocable: boolean;
+    userInvocable: boolean;
+    requestedPreapprovedTools: string[];
+    toolPolicy: XenoSkillToolPolicy;
+    externalActions: XenoSkillExternalActionPolicy;
+    contentHash: string;
+    instructionBytes: number;
+    resources: XenoSkillResourceDescriptor[];
+}
+interface XenoSkillDiagnostic {
+    severity: "warning" | "error";
+    code: "SKILL_ROOT_UNREADABLE" | "SKILL_INVALID" | "SKILL_SYMLINK_REJECTED" | "SKILL_RESOURCE_LIMIT" | "SKILL_AMBIGUOUS";
+    message: string;
+    path?: string;
+    key?: string;
+}
+interface XenoSkillShadowRecord {
+    key: string;
+    selected: XenoSkillDescriptor;
+    shadowed: XenoSkillDescriptor[];
+}
+interface XenoSkillCatalog {
+    schemaVersion: typeof XENO_SKILL_SCHEMA_VERSION;
+    generatedAt: string;
+    catalogHash: string;
+    skills: XenoSkillDescriptor[];
+    shadowed: XenoSkillShadowRecord[];
+    diagnostics: XenoSkillDiagnostic[];
+}
+interface XenoLoadedSkill {
+    descriptor: XenoSkillDescriptor;
+    instructions: string;
+}
+interface XenoSkillDiscoveryOptions {
+    roots: XenoSkillDiscoveryRoot[];
+    maxSkills?: number;
+    maxSkillBytes?: number;
+    maxResourceFiles?: number;
+    maxResourceBytes?: number;
+    now?: () => Date;
+}
+interface XenoSkillInvocationPolicy {
+    allow?: string[];
+    deny?: string[];
+    externalActions?: XenoSkillExternalActionPolicy;
+}
+interface XenoSkillActivation {
+    descriptor: XenoSkillDescriptor;
+    arguments: string;
+    toolAllowLayers: string[][];
+    effectiveAllowedTools?: string[];
+    effectiveDeniedTools: string[];
+    externalActions: XenoSkillExternalActionPolicy;
+}
+interface XenoSkillAuditEvent {
+    schemaVersion: typeof XENO_SKILL_SCHEMA_VERSION;
+    type: "skill-invoked" | "skill-denied" | "skill-load-failed";
+    recordedAt: string;
+    skillKey: string;
+    skillHash: string;
+    invocation: "model" | "user";
+    argumentsHash?: string;
+    reason?: string;
+}
+interface CreateXenoSkillToolOptions {
+    getCatalog: () => XenoSkillCatalog;
+    loadSkill?: (descriptor: XenoSkillDescriptor) => XenoLoadedSkill | Promise<XenoLoadedSkill>;
+    invocationPolicy?: XenoSkillInvocationPolicy | (() => XenoSkillInvocationPolicy | undefined);
+    authorize?: (descriptor: XenoSkillDescriptor, invocation: "model" | "user") => XenoSkillInvocationDecision | Promise<XenoSkillInvocationDecision>;
+    ask?: (descriptor: XenoSkillDescriptor) => Promise<boolean>;
+    onActivate?: (activation: XenoSkillActivation) => void | Promise<void>;
+    onAudit?: (event: XenoSkillAuditEvent) => void | Promise<void>;
+    now?: () => Date;
+    projectDirectory?: string | (() => string);
+}
+type XenoSkillTool = RegisteredTool;
+interface LegacyXenoSkillInput {
+    id: string;
+    name?: string;
+    description?: string;
+    content: string;
+    path?: string;
+    source?: Extract<XenoSkillSource, "user" | "project" | "plugin" | "legacy">;
+    precedence?: number;
+    namespace?: string;
+    version?: string;
+    allowedTools?: string[];
+    modelInvocable?: boolean;
+    userInvocable?: boolean;
+    toolPolicy?: XenoSkillToolPolicy;
+    externalActions?: XenoSkillExternalActionPolicy;
+}
+declare function discoverXenoSkills(options: XenoSkillDiscoveryOptions): XenoSkillCatalog;
+declare function loadXenoSkill(descriptor: XenoSkillDescriptor): XenoLoadedSkill;
+declare function importLegacyXenoSkill(input: LegacyXenoSkillInput): XenoLoadedSkill;
+declare function renderXenoSkillCatalog(catalog: XenoSkillCatalog): string;
+declare function findXenoSkill(catalog: XenoSkillCatalog, reference: string): XenoSkillDescriptor | undefined;
+declare function createXenoSkillTool(options: CreateXenoSkillToolOptions): XenoSkillTool;
+declare function invokeXenoSkill(options: CreateXenoSkillToolOptions & {
+    name: string;
+    arguments?: string;
+    invocation: "model" | "user";
+}): Promise<{
+    loaded: XenoLoadedSkill;
+    activation: XenoSkillActivation;
+    output: string;
+}>;
+declare function compileXenoSkillActivation(descriptor: XenoSkillDescriptor, argumentsValue?: string, outerPolicy?: XenoSkillInvocationPolicy): XenoSkillActivation;
+declare function isToolAllowedByXenoSkillActivation(activation: XenoSkillActivation, toolName: string): boolean;
+export { type CreateXenoSkillToolOptions, type LegacyXenoSkillInput, XENO_SKILL_SCHEMA_VERSION, type XenoLoadedSkill, type XenoSkillActivation, type XenoSkillAuditEvent, type XenoSkillCatalog, type XenoSkillDescriptor, type XenoSkillDiagnostic, type XenoSkillDiscoveryOptions, type XenoSkillDiscoveryRoot, type XenoSkillExternalActionPolicy, type XenoSkillInvocationDecision, type XenoSkillInvocationPolicy, type XenoSkillResourceDescriptor, type XenoSkillShadowRecord, type XenoSkillSource, type XenoSkillTool, type XenoSkillToolPolicy, compileXenoSkillActivation, createXenoSkillTool, discoverXenoSkills, findXenoSkill, importLegacyXenoSkill, invokeXenoSkill, isToolAllowedByXenoSkillActivation, loadXenoSkill, renderXenoSkillCatalog };

package/dist/skills/index.js

@@ -0,0 +1,6 @@
+var g=2;import{createHash as ye}from"node:crypto";import{lstatSync as T,readFileSync as _,readdirSync as z,realpathSync as M,statSync as H}from"node:fs";import{basename as U,dirname as Y,join as E,relative as ge,resolve as $,sep as ke}from"node:path";function A(e){let n=me(e);return{frontmatter:n.frontmatter,content:n.content.trim()}}function me(e){let n=e.replace(/^\uFEFF/,"");if(!n.startsWith("---"))return{frontmatter:{},content:e};let t=n.search(/\r?\n/);if(t<0||n.slice(0,t).trim()!=="---")return{frontmatter:{},content:e};let o=n.slice(t+(n[t]==="\r"?2:1)),r=o.match(/(?:^|\r?\n)---[ \t]*(?:\r?\n|$)/);if(!r||r.index===void 0)throw new Error("YAML frontmatter is not closed.");let i=o.slice(0,r.index),c=r[0],d=r.index+c.length;return{frontmatter:j(i),content:o.slice(d)}}function j(e){let n={},t=e.split(/\r?\n/);for(let o=0;o<t.length;o+=1){let r=t[o];if(!r.trim()||r.trimStart().startsWith("#"))continue;if(/^\s/.test(r))throw new Error(`Unexpected indentation at line ${o+1}.`);let i=pe(r,o+1);if(i.key==="<<")throw new Error("YAML merge keys are not supported.");if(i.value!==""){n[i.key]=K(i.value,o+1);continue}let c=fe(t,o+1);n[i.key]=c.value,o=c.nextIndex-1}return n}function fe(e,n){let t=[],o=n;for(;o<e.length;o+=1){let i=e[o];if(!i.trim()){t.push(i);continue}if(!/^\s/.test(i))break;t.push(i.replace(/^ {2}/,""))}let r=t.filter(i=>i.trim()&&!i.trimStart().startsWith("#"));return r.length===0?{value:{},nextIndex:o}:r.every(i=>i.trimStart().startsWith("- "))?{value:r.map((i,c)=>K(i.trimStart().slice(2),n+c+1)),nextIndex:o}:{value:j(t.join(`
+`)),nextIndex:o}}function pe(e,n){let t=e.indexOf(":");if(t<=0)throw new Error(`Invalid YAML line ${n}.`);let o=e.slice(0,t).trim(),r=e.slice(t+1).trim();if(!o)throw new Error(`Invalid YAML key at line ${n}.`);return{key:o,value:r}}function K(e,n){if(e==="")return"";if(e==="[]")return[];if(e==="{}")return{};if(e==="true")return!0;if(e==="false")return!1;if(e==="null"||e==="~")return null;if(/^-?\d+(?:\.\d+)?$/.test(e))return Number(e);if(e.startsWith('"'))return N(e,n);if(e.startsWith("'")){if(!e.endsWith("'"))throw new Error(`Unclosed quoted scalar at line ${n}.`);return e.slice(1,-1).replace(/''/g,"'")}if(e.startsWith("[")||e.startsWith("{"))return N(e,n);if(e.includes("[")||e.includes("]")||e.includes("{")||e.includes("}"))throw new Error(`Unsupported YAML scalar at line ${n}.`);return e}function N(e,n){try{return JSON.parse(e)}catch{throw new Error(`Invalid YAML scalar at line ${n}.`)}}var R=/^[a-z0-9]+(?:-[a-z0-9]+)*$/u,Se=2e3,W=2*1024*1024,J=2e3,G=64*1024*1024;function Ke(e){let n={maxSkills:X(e.maxSkills,Se,1,2e4),maxSkillBytes:X(e.maxSkillBytes,W,1024,16777216),maxResourceFiles:X(e.maxResourceFiles,J,0,2e4),maxResourceBytes:X(e.maxResourceBytes,G,0,536870912)},t=[],o=[],r=new Set;for(let s of e.roots){if(o.length>=n.maxSkills)break;let l=$(s.path),a;try{if(!H(l,{throwIfNoEntry:!1})?.isDirectory())continue;a=z(l,{withFileTypes:!0}).sort((m,f)=>m.name.localeCompare(f.name))}catch(m){t.push({severity:"warning",code:"SKILL_ROOT_UNREADABLE",message:`Unable to inspect skill root: ${V(m)}`,path:l});continue}for(let m of a){if(o.length>=n.maxSkills)break;let f=E(l,m.name);try{let p=T(f);if(p.isSymbolicLink()&&!s.followSymlinks){t.push({severity:"warning",code:"SKILL_SYMLINK_REJECTED",message:"Skill directory symlinks require an explicitly trusted discovery root",path:f});continue}let u=p.isSymbolicLink()?M(f):f;if(!H(u).isDirectory())continue;let y=M(u);if(r.has(y))continue;let S=ee(y,s,n,t);if(!S)continue;r.add(y),o.push(S.descriptor)}catch(p){t.push({severity:"error",code:"SKILL_INVALID",message:V(p),path:f})}}}let i=new Map;for(let s of o){let l=i.get(s.key)??[];l.push(s),i.set(s.key,l)}let c=[],d=[];for(let[s,l]of[...i].sort(([a],[m])=>a.localeCompare(m))){let a=l.sort((u,y)=>y.precedence-u.precedence||u.entrypoint.localeCompare(y.entrypoint)),m=a[0]?.precedence,f=a.filter(u=>u.precedence===m);if(f.length>1&&new Set(f.map(u=>u.contentHash)).size>1){t.push({severity:"error",code:"SKILL_AMBIGUOUS",key:s,message:`Skill ${s} has conflicting definitions at precedence ${m}; qualify or remove one definition`});continue}let p=a[0];c.push(p),a.length>1&&d.push({key:s,selected:p,shadowed:a.slice(1)})}return c.sort((s,l)=>s.key.localeCompare(l.key)),{schemaVersion:2,generatedAt:(e.now?.()??new Date).toISOString(),catalogHash:L(k(c.map(Xe))),skills:c,shadowed:d,diagnostics:t}}function Q(e){if(e.source==="legacy"){let r=A(_(e.entrypoint,"utf8")).content.trim();if(ne(e,r)!==e.contentHash)throw new Error(`Skill ${e.key} changed after discovery; refresh the catalog before invoking it`);return{descriptor:structuredClone(e),instructions:r}}let n=[],t=ee(e.directory,{path:Y(e.directory),source:e.source,precedence:e.precedence,...e.namespace?{namespace:e.namespace}:{},followSymlinks:!1},{maxSkills:1,maxSkillBytes:Math.max(W,e.instructionBytes),maxResourceFiles:Math.max(J,e.resources.length),maxResourceBytes:Math.max(G,e.resources.reduce((o,r)=>o+r.sizeBytes,0))},n);if(!t||n.some(o=>o.severity==="error"))throw new Error(`Unable to load skill ${e.key}: ${n.map(o=>o.message).join("; ")||"invalid skill"}`);if(t.descriptor.contentHash!==e.contentHash)throw new Error(`Skill ${e.key} changed after discovery; refresh the catalog before invoking it`);return{descriptor:structuredClone(e),instructions:t.instructions}}function Me(e){let n=e.id.trim().toLowerCase();if(!R.test(n)||n.length>64)throw new Error(`Legacy skill name is invalid: ${e.id}`);let t=e.content.trim();if(!t)throw new Error("Legacy skill content cannot be empty");let o=e.path?Y($(e.path)):process.cwd(),r={schemaVersion:2,key:e.namespace?`${e.namespace}:${n}`:n,name:n,description:e.description?.trim()||e.name?.trim()||`Imported legacy XENO skill ${n}`,source:"legacy",precedence:e.precedence??0,directory:o,entrypoint:e.path?$(e.path):E(o,`${n}.md`),...e.namespace?{namespace:e.namespace}:{},...e.version?{version:e.version}:{},metadata:{"xeno.imported-from":e.source??"legacy"},modelInvocable:e.modelInvocable??!0,userInvocable:e.userInvocable??!0,requestedPreapprovedTools:[...new Set(e.allowedTools??[])].sort(),toolPolicy:te(e.toolPolicy),externalActions:e.externalActions??"ask",contentHash:"",instructionBytes:Buffer.byteLength(t,"utf8"),resources:[]};return r.contentHash=ne(r,t),{descriptor:r,instructions:t}}function He(e){let n=e.skills.filter(t=>t.modelInvocable);return n.length===0?"":["<available_skills>",...n.flatMap(t=>["  <skill>",`    <name>${q(t.key)}</name>`,`    <description>${q(t.description)}</description>`,`    <hash>${t.contentHash}</hash>`,"  </skill>"]),"</available_skills>","Use the Skill tool to load full instructions only when a listed skill is relevant."].join(`
+`)}function Z(e,n){let t=n.trim().toLowerCase();if(!t)return;let o=e.skills.find(i=>i.key.toLowerCase()===t);if(o)return o;let r=e.skills.filter(i=>i.name.toLowerCase()===t);return r.length===1?r[0]:void 0}function ee(e,n,t,o){let r=E(e,"SKILL.md"),i=T(r,{throwIfNoEntry:!1});if(!i)return;if(i.isSymbolicLink()||!i.isFile())throw new Error("SKILL.md must be a regular, non-symlink file");if(i.size>t.maxSkillBytes)throw new Error(`SKILL.md exceeds ${t.maxSkillBytes} bytes`);let c=_(r,"utf8"),d=A(c),s=d.frontmatter,l=F(s.name,"name"),a=F(s.description,"description");if(!R.test(l)||l.length>64)throw new Error(`Skill name does not match ${R.source} or exceeds 64 characters`);if(l!==U(e))throw new Error(`Skill name ${l} must match its parent directory ${U(e)}`);if(a.length>1024)throw new Error("Skill description exceeds 1024 characters");let m=P(s.license,"license"),f=P(s.compatibility,"compatibility");if(f&&f.length>500)throw new Error("Skill compatibility exceeds 500 characters");let p=xe(s.metadata,"metadata"),u=x(s.xeno),y=D(s["allowed-tools"]??s.allowedTools),S=te({allow:D(u?.["allowed-tools"]??u?.allowedTools??x(u?.tools)?.allow),deny:D(u?.["denied-tools"]??u?.deniedTools??x(u?.tools)?.deny)}),ce=Ee(u?.["external-actions"]??u?.externalActions),ae=!(w(s["disable-model-invocation"])??!1)&&(w(u?.modelInvocable)??!0),ue=w(s["user-invocable"])??w(u?.userInvocable)??!0,C=he(e,r,t,o),I=d.content.trim();if(!I)throw new Error("SKILL.md instructions cannot be empty");let de=L(k({raw:c,resources:C.map(B=>({path:B.relativePath,sha256:B.sha256}))})),h=n.namespace?.trim();return{descriptor:{schemaVersion:2,key:h?`${h}:${l}`:l,name:l,description:a,source:n.source,precedence:n.precedence,directory:e,entrypoint:r,...h?{namespace:h}:{},...p.version?{version:p.version}:{},...m?{license:m}:{},...f?{compatibility:f}:{},metadata:p,modelInvocable:ae,userInvocable:ue,requestedPreapprovedTools:y,toolPolicy:S,externalActions:ce,contentHash:de,instructionBytes:Buffer.byteLength(I,"utf8"),resources:C},instructions:I}}function he(e,n,t,o){let r=[],i=0,c=d=>{for(let s of z(d,{withFileTypes:!0}).sort((l,a)=>l.name.localeCompare(a.name))){let l=E(d,s.name);if(l===n)continue;let a=T(l);if(a.isSymbolicLink()){o.push({severity:"warning",code:"SKILL_SYMLINK_REJECTED",message:"Skill resource symlinks are not included",path:l});continue}if(a.isDirectory()){c(l);continue}if(!a.isFile())continue;if(r.length>=t.maxResourceFiles)throw new Error(`Skill resource count exceeds ${t.maxResourceFiles}`);if(i+=a.size,i>t.maxResourceBytes)throw new Error(`Skill resources exceed ${t.maxResourceBytes} bytes`);let m=ge(e,l).split(ke).join("/");r.push({relativePath:m,kind:we(m),sizeBytes:a.size,sha256:L(_(l))})}};return c(e),r.sort((d,s)=>d.relativePath.localeCompare(s.relativePath))}function we(e){let n=e.split("/",1)[0]?.toLowerCase();return n==="scripts"?"script":n==="references"?"reference":n==="assets"?"asset":n==="templates"?"template":"other"}function Xe(e){return{key:e.key,source:e.source,precedence:e.precedence,contentHash:e.contentHash,modelInvocable:e.modelInvocable,userInvocable:e.userInvocable}}function ne(e,n){return L(k({key:e.key,description:e.description,instructions:n,requestedPreapprovedTools:e.requestedPreapprovedTools,toolPolicy:e.toolPolicy,externalActions:e.externalActions}))}function te(e){let n=[...new Set(e?.allow?.map(o=>o.trim()).filter(Boolean)??[])].sort(),t=[...new Set(e?.deny?.map(o=>o.trim()).filter(Boolean)??[])].sort();return{...n.length>0?{allow:n}:{},...t.length>0?{deny:t}:{}}}function D(e){return typeof e=="string"?[...new Set(e.split(/\s+/u).map(n=>n.trim()).filter(Boolean))].sort():Array.isArray(e)?[...new Set(e.filter(n=>typeof n=="string").map(n=>n.trim()).filter(Boolean))].sort():[]}function xe(e,n){if(e===void 0)return{};let t=x(e);if(!t)throw new Error(`${n} must be a string-to-string mapping`);let o={};for(let[r,i]of Object.entries(t)){if(typeof i!="string")throw new Error(`${n}.${r} must be a string`);o[r]=i}return o}function F(e,n){let t=P(e,n);if(!t)throw new Error(`Skill ${n} is required`);return t}function P(e,n){if(e===void 0)return;if(typeof e!="string")throw new Error(`Skill ${n} must be a string`);let t=e.trim();if(!t)throw new Error(`Skill ${n} cannot be empty`);return t}function x(e){return e&&typeof e=="object"&&!Array.isArray(e)?e:void 0}function w(e){return typeof e=="boolean"?e:void 0}function Ee(e){return e==="deny"||e==="allow"||e==="ask"?e:"ask"}function X(e,n,t,o){if(e===void 0)return n;if(!Number.isInteger(e)||e<t||e>o)throw new Error(`Skill discovery limit must be an integer between ${t} and ${o}`);return e}function k(e){return Array.isArray(e)?`[${e.map(k).join(",")}]`:e&&typeof e=="object"?`{${Object.entries(e).filter(([,n])=>n!==void 0).sort(([n],[t])=>n.localeCompare(t)).map(([n,t])=>`${JSON.stringify(n)}:${k(t)}`).join(",")}}`:JSON.stringify(e)??"null"}function L(e){return ye("sha256").update(e).digest("hex")}function q(e){return e.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")}function V(e){return e instanceof Error?e.message:String(e)}import{createHash as Le}from"node:crypto";var oe=128*1024;function ze(e){return{definition:{name:"Skill",description:"Load one available SKILL.md instruction body on demand. Use only a name from <available_skills>.",input_schema:{type:"object",properties:{name:{type:"string",description:"Exact skill key or unique skill name"},arguments:{type:"string",description:"Optional arguments supplied to the skill"}},required:["name"],additionalProperties:!1}},projectPolicyInput:n=>({observabilityInput:{name:typeof n.name=="string"?n.name:"",hasArguments:typeof n.arguments=="string"&&n.arguments.length>0},permissionInput:{name:typeof n.name=="string"?n.name:""},permissionPreview:`Load skill ${typeof n.name=="string"?n.name:""}`,approvalKey:`skill:${typeof n.name=="string"?n.name:"unknown"}`,riskLevel:"low"}),execute:async n=>{let t=typeof n.name=="string"?n.name.trim():"",o=typeof n.arguments=="string"?n.arguments.trim():"";if(!t)return ie("SKILL_INVALID_INPUT","Skill name is required");try{return{success:!0,output:(await be({...e,name:t,arguments:o,invocation:"model"})).output}}catch(r){return ie("SKILL_INVOCATION_DENIED",O(r))}}}}async function be(e){let n=e.getCatalog(),t=Z(n,e.name);if(!t)throw new Error(`Skill not found or ambiguous: ${e.name}`);let o=e.arguments?.trim()??"",r={schemaVersion:2,recordedAt:(e.now?.()??new Date).toISOString(),skillKey:t.key,skillHash:t.contentHash,invocation:e.invocation,...o?{argumentsHash:Re(o)}:{}};try{let i=await Ie(t,e.invocation,e);if(i==="deny")throw await b(e,{...r,type:"skill-denied",reason:"Invocation policy denied the skill"}),new Error(`Skill ${t.key} is denied by the active policy`);if(i==="ask"&&(!e.ask||!await e.ask(t)))throw await b(e,{...r,type:"skill-denied",reason:"User did not approve skill invocation"}),new Error(`Skill ${t.key} requires approval`);let c=await(e.loadSkill??Q)(t);if(c.descriptor.contentHash!==t.contentHash)throw new Error(`Skill ${t.key} loader returned a mismatched content hash`);let d=le(e.invocationPolicy),s=se(t,o,d);await e.onActivate?.(structuredClone(s));let l=ve(c,s,{arguments:o,projectDirectory:typeof e.projectDirectory=="function"?e.projectDirectory():e.projectDirectory});if(Buffer.byteLength(l,"utf8")>oe)throw new Error(`Skill ${t.key} exceeds the ${oe}-byte invocation limit; move details into references/`);return await b(e,{...r,type:"skill-invoked"}),{loaded:c,activation:s,output:l}}catch(i){throw/denied by the active policy|requires approval/u.test(O(i))||await b(e,{...r,type:"skill-load-failed",reason:O(i)}),i}}function Ye(e,n="",t){return se(e,n,t)}function se(e,n,t){let o=re(t?.allow),r=re(e.toolPolicy.allow),i=[o,r].filter(s=>s!==void 0),c=i.length<=1?i[0]:void 0,d=[...new Set([...e.toolPolicy.deny??[],...t?.deny??[]])].sort();return{descriptor:structuredClone(e),arguments:n,toolAllowLayers:i,...c?{effectiveAllowedTools:c}:{},effectiveDeniedTools:d,externalActions:Ae(e.externalActions,t?.externalActions??"allow")}}function We(e,n){return v(n,e.effectiveDeniedTools)?!1:e.toolAllowLayers.every(t=>v(n,t))}function ve(e,n,t){let o=e.descriptor,r=e.instructions,i=/\$ARGUMENTS(?:\[\d+\])?|\$\d+/u.test(r),c=$e(t.arguments);r=r.replace(/\$ARGUMENTS\[(\d+)\]/gu,(s,l)=>c[Number.parseInt(l,10)]??"").replace(/\$(\d+)\b/gu,(s,l)=>c[Number.parseInt(l,10)]??"").replace(/\$ARGUMENTS\b/gu,t.arguments).replace(/\$\{(?:XENO|CLAUDE)_SKILL_DIR\}/gu,o.directory).replace(/\$\{(?:XENO|CLAUDE)_PROJECT_DIR\}/gu,t.projectDirectory??process.cwd()),t.arguments&&!i&&(r+=`
+
+ARGUMENTS: ${t.arguments}`);let d=o.resources.length>0?["","Bundled resources (load only when needed; paths are relative to the skill directory):",...o.resources.map(s=>`- ${s.relativePath} (${s.kind}, ${s.sizeBytes} bytes, sha256:${s.sha256})`)]:[];return[`<xeno_skill key="${Pe(o.key)}" hash="${o.contentHash}">`,`Source: ${o.source}`,`External actions: ${n.externalActions}`,...n.toolAllowLayers.map((s,l)=>`Tool allow layer ${l+1}: ${s.join(", ")||"none"}`),...n.effectiveDeniedTools.length>0?[`Denied tools: ${n.effectiveDeniedTools.join(", ")}`]:[],o.requestedPreapprovedTools.length>0?`Requested pre-approvals (not authority grants): ${o.requestedPreapprovedTools.join(", ")}`:"Requested pre-approvals: none","",r,...d,"</xeno_skill>"].join(`
+`)}async function Ie(e,n,t){if(n==="model"&&!e.modelInvocable||n==="user"&&!e.userInvocable)return"deny";let o=le(t.invocationPolicy);return v(e.key,o?.deny??[])||o?.allow&&!v(e.key,o.allow)?"deny":t.authorize?t.authorize(e,n):"allow"}function le(e){return typeof e=="function"?e():e}function Ae(e,n){let t={deny:0,ask:1,allow:2};return t[e]<=t[n]?e:n}function re(e){if(e)return[...new Set(e.map(n=>n.trim()).filter(Boolean))].sort()}function v(e,n){let t=e.toLowerCase();return n.some(o=>{let r=o.trim().toLowerCase();return r?new RegExp(`^${r.split("*").map(De).join(".*")}$`,"u").test(t):!1})}function De(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function $e(e){return(e.match(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\S+/gu)??[]).map(t=>t.startsWith('"')&&t.endsWith('"')||t.startsWith("'")&&t.endsWith("'")?t.slice(1,-1):t)}async function b(e,n){await e.onAudit?.(n)}function ie(e,n){return{success:!1,output:n,error:n,errorCode:e}}function Re(e){return Le("sha256").update(e).digest("hex")}function Pe(e){return e.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")}function O(e){return e instanceof Error?e.message:String(e)}export{g as XENO_SKILL_SCHEMA_VERSION,Ye as compileXenoSkillActivation,ze as createXenoSkillTool,Ke as discoverXenoSkills,Z as findXenoSkill,Me as importLegacyXenoSkill,be as invokeXenoSkill,We as isToolAllowedByXenoSkillActivation,Q as loadXenoSkill,He as renderXenoSkillCatalog};

package/dist/skills/metafile-cjs.json

@@ -0,0 +1 @@
+{"inputs":{"src/skills/types.ts":{"bytes":5049,"imports":[],"format":"esm"},"src/utils/yaml.ts":{"bytes":5668,"imports":[],"format":"esm"},"src/skills/catalog.ts":{"bytes":19399,"imports":[{"path":"node:crypto","kind":"import-statement","external":true},{"path":"node:fs","kind":"import-statement","external":true},{"path":"node:path","kind":"import-statement","external":true},{"path":"src/utils/yaml.ts","kind":"import-statement","original":"../utils/yaml.js"},{"path":"src/skills/types.ts","kind":"import-statement","original":"./types.js"}],"format":"esm"},"src/skills/tool.ts":{"bytes":11774,"imports":[{"path":"node:crypto","kind":"import-statement","external":true},{"path":"src/skills/catalog.ts","kind":"import-statement","original":"./catalog.js"},{"path":"src/skills/types.ts","kind":"import-statement","original":"./types.js"}],"format":"esm"},"src/skills/index.ts":{"bytes":88,"imports":[{"path":"src/skills/types.ts","kind":"import-statement","original":"./types.js"},{"path":"src/skills/catalog.ts","kind":"import-statement","original":"./catalog.js"},{"path":"src/skills/tool.ts","kind":"import-statement","original":"./tool.js"}],"format":"esm"}},"outputs":{"dist/skills/index.cjs":{"imports":[{"path":"node:crypto","kind":"require-call","external":true},{"path":"node:fs","kind":"require-call","external":true},{"path":"node:path","kind":"require-call","external":true},{"path":"node:crypto","kind":"require-call","external":true}],"exports":[],"entryPoint":"src/skills/index.ts","inputs":{"src/skills/index.ts":{"bytesInOutput":324},"src/skills/types.ts":{"bytesInOutput":8},"src/skills/catalog.ts":{"bytesInOutput":9696},"src/utils/yaml.ts":{"bytesInOutput":2217},"src/skills/tool.ts":{"bytesInOutput":5403}},"bytes":18322}}}

package/dist/skills/metafile-esm.json

@@ -0,0 +1 @@
+{"inputs":{"src/skills/types.ts":{"bytes":5049,"imports":[],"format":"esm"},"src/utils/yaml.ts":{"bytes":5668,"imports":[],"format":"esm"},"src/skills/catalog.ts":{"bytes":19399,"imports":[{"path":"node:crypto","kind":"import-statement","external":true},{"path":"node:fs","kind":"import-statement","external":true},{"path":"node:path","kind":"import-statement","external":true},{"path":"src/utils/yaml.ts","kind":"import-statement","original":"../utils/yaml.js"},{"path":"src/skills/types.ts","kind":"import-statement","original":"./types.js"}],"format":"esm"},"src/skills/tool.ts":{"bytes":11774,"imports":[{"path":"node:crypto","kind":"import-statement","external":true},{"path":"src/skills/catalog.ts","kind":"import-statement","original":"./catalog.js"},{"path":"src/skills/types.ts","kind":"import-statement","original":"./types.js"}],"format":"esm"},"src/skills/index.ts":{"bytes":88,"imports":[{"path":"src/skills/types.ts","kind":"import-statement","original":"./types.js"},{"path":"src/skills/catalog.ts","kind":"import-statement","original":"./catalog.js"},{"path":"src/skills/tool.ts","kind":"import-statement","original":"./tool.js"}],"format":"esm"}},"outputs":{"dist/skills/index.js":{"imports":[{"path":"node:crypto","kind":"import-statement","external":true},{"path":"node:fs","kind":"import-statement","external":true},{"path":"node:path","kind":"import-statement","external":true},{"path":"node:crypto","kind":"import-statement","external":true}],"exports":["XENO_SKILL_SCHEMA_VERSION","compileXenoSkillActivation","createXenoSkillTool","discoverXenoSkills","findXenoSkill","importLegacyXenoSkill","invokeXenoSkill","isToolAllowedByXenoSkillActivation","loadXenoSkill","renderXenoSkillCatalog"],"entryPoint":"src/skills/index.ts","inputs":{"src/skills/types.ts":{"bytesInOutput":8},"src/skills/index.ts":{"bytesInOutput":0},"src/skills/catalog.ts":{"bytesInOutput":9541},"src/utils/yaml.ts":{"bytesInOutput":2217},"src/skills/tool.ts":{"bytesInOutput":5407}},"bytes":17455}}}

package/dist/soul/index.cjs

@@ -0,0 +1,32 @@
+"use strict";var x=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var z=Object.getOwnPropertyNames;var j=Object.prototype.hasOwnProperty;var N=(n,e)=>{for(var t in e)x(n,t,{get:e[t],enumerable:!0})},F=(n,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of z(e))!j.call(n,i)&&i!==t&&x(n,i,{get:()=>e[i],enumerable:!(r=A(e,i))||r.enumerable});return n};var K=n=>F(x({},"__esModule",{value:!0}),n);var q={};N(q,{EpisodicStore:()=>u,SkillStore:()=>p,SoulEngine:()=>b,canonicalPayload:()=>g,createEd25519Signer:()=>v,extractJsonObject:()=>y,synthesizeSkill:()=>k,verifySignature:()=>E,verifySoulRecord:()=>I});module.exports=K(q);var w=class{dimension;idfCounts=new Map;totalDocs=0;constructor(e){this.dimension=e}tokenize(e){return e.toLowerCase().replace(/[^a-z0-9\s]/g," ").split(/\s+/).filter(t=>t.length>1&&t.length<40)}hashToDim(e){let t=0;for(let r=0;r<e.length;r++)t=(t<<5)-t+e.charCodeAt(r)|0;return Math.abs(t)%this.dimension}updateIdf(e){let t=new Set(this.tokenize(e));for(let r of t)this.idfCounts.set(r,(this.idfCounts.get(r)??0)+1);this.totalDocs++}embed(e){let t=new Float64Array(this.dimension),r=this.tokenize(e);if(r.length===0)return Array.from(t);let i=new Map;for(let s of r)i.set(s,(i.get(s)??0)+1);for(let[s,a]of i){let c=a/r.length,h=this.idfCounts.get(s)??0,S=h>0?Math.log((this.totalDocs+1)/(h+1))+1:1,R=c*S,C=this.hashToDim(s);t[C]+=R}let o=0;for(let s=0;s<this.dimension;s++)o+=t[s]*t[s];if(o=Math.sqrt(o),o>0)for(let s=0;s<this.dimension;s++)t[s]=t[s]/o;return Array.from(t)}};function V(n,e){if(n.length!==e.length)return 0;let t=0,r=0,i=0;for(let s=0;s<n.length;s++)t+=n[s]*e[s],r+=n[s]*n[s],i+=e[s]*e[s];let o=Math.sqrt(r)*Math.sqrt(i);return o>0?t/o:0}var m=class{documents=new Map;insertionOrder=[];maxDocuments;embedder;customEmbedFn;constructor(e){this.maxDocuments=e?.maxDocuments??1e4,this.embedder=new w(e?.embeddingDimension??256),this.customEmbedFn=e?.embedFn}async addDocument(e,t,r={}){for(;this.documents.size>=this.maxDocuments&&this.insertionOrder.length>0;){let s=this.insertionOrder.shift();this.documents.delete(s)}this.embedder.updateIdf(t);let i=this.customEmbedFn?await this.customEmbedFn(t):this.embedder.embed(t),o={id:e,content:t,embedding:i,metadata:r};this.documents.set(e,o),this.insertionOrder.push(e)}async search(e,t=5,r=.1){let i=this.customEmbedFn?await this.customEmbedFn(e):this.embedder.embed(e),o=[];for(let s of this.documents.values()){let a=V(i,s.embedding);a>=r&&o.push({id:s.id,content:s.content,score:a,metadata:s.metadata})}return o.sort((s,a)=>a.score-s.score),o.slice(0,t)}removeDocument(e){let t=this.documents.delete(e);if(t){let r=this.insertionOrder.indexOf(e);r>=0&&this.insertionOrder.splice(r,1)}return t}getDocument(e){return this.documents.get(e)}get size(){return this.documents.size}clear(){this.documents.clear(),this.insertionOrder=[]}exportDocuments(){return Array.from(this.documents.values())}importDocuments(e){for(let t of e)this.documents.set(t.id,t),this.insertionOrder.push(t.id)}};function J(n){return[n.task,n.summary,...n.tags??[]].filter(Boolean).join(`
+`)}var u=class n{index;byId=new Map;constructor(e={}){this.index=new m({maxDocuments:e.maxEpisodes??5e3})}async add(e){this.byId.set(e.id,e),await this.index.addDocument(e.id,J(e),{kind:"episode",outcome:e.outcome})}async recall(e,t=5,r=.1){let i=await this.index.search(e,t,r),o=[];for(let s of i){let a=this.byId.get(s.id);a&&o.push({episode:a,score:s.score})}return o}get(e){return this.byId.get(e)}all(){return[...this.byId.values()]}get size(){return this.byId.size}toJSON(){return this.all()}static async fromEpisodes(e,t={}){let r=new n(t);for(let i of e)await r.add(i);return r}};function M(n){return[n.name,n.trigger,...n.tags??[]].filter(Boolean).join(`
+`)}var p=class n{index;byId=new Map;constructor(e={}){this.index=new m({maxDocuments:e.maxSkills??5e3})}async add(e){this.byId.set(e.id,e),await this.index.addDocument(e.id,M(e),{kind:"skill",name:e.name})}async recall(e,t=5,r=.1){let i=await this.index.search(e,t,r),o=[];for(let s of i){let a=this.byId.get(s.id);a&&o.push({skill:a,score:s.score})}return o}nextVersion(e){let t=0;for(let r of this.byId.values())r.name===e&&r.version>t&&(t=r.version);return t+1}get(e){return this.byId.get(e)}all(){return[...this.byId.values()]}get size(){return this.byId.size}toJSON(){return this.all()}static async fromSkills(e,t={}){let r=new n(t);for(let i of e)await r.add(i);return r}};var O=require("node:crypto");function y(n){let e=n.indexOf("{");if(e<0)return null;let t=0,r=!1,i=!1;for(let o=e;o<n.length;o++){let s=n[o];if(r){i?i=!1:s==="\\"?i=!0:s==='"'&&(r=!1);continue}if(s==='"')r=!0;else if(s==="{")t++;else if(s==="}"&&(t--,t===0)){let a=n.slice(e,o+1);try{let c=JSON.parse(a);return c&&typeof c=="object"&&!Array.isArray(c)?c:null}catch{return null}}}return null}function g(n){let e=t=>{if(Array.isArray(t))return t.map(e);if(t&&typeof t=="object"){let r=t,i={};for(let o of Object.keys(r).sort())o!=="signature"&&(i[o]=e(r[o]));return i}return t};return JSON.stringify(e(n))}var $=`You distill REUSABLE SKILLS from a completed agent task.
+Given the task and a transcript of how it was solved, extract ONE general, reusable
+procedure that would help on similar future tasks \u2014 not a recap of this specific run.
+
+Respond with ONLY a JSON object, no prose, no code fences:
+{
+  "name": "<short imperative skill name>",
+  "trigger": "<when to use this skill \u2014 the situation that should recall it>",
+  "procedure": "<numbered, reusable steps>",
+  "tags": ["<short>", "<keywords>"]
+}
+If no general skill is worth keeping, respond with exactly: {}`,G=6e3;function L(n,e){return n.length<=e?n:n.slice(0,e)+`
+\u2026[truncated]`}async function k(n){let e=n.now??(()=>new Date),t=n.idGen??(()=>(0,O.randomUUID)()),r=`TASK:
+${n.task}
+
+TRANSCRIPT:
+${L(n.transcript,G)}
+
+Produce one reusable skill as JSON, or {} if none is worth keeping.`,i;try{i=await n.complete([{role:"system",content:$},{role:"user",content:r}])}catch{return null}let o=y(i);if(!o)return null;let s=typeof o.name=="string"?o.name.trim():"",a=typeof o.procedure=="string"?o.procedure.trim():"";if(!s||!a)return null;let c=typeof o.trigger=="string"?o.trigger.trim():"",h=Array.isArray(o.tags)?o.tags.filter(S=>typeof S=="string"&&S.trim().length>0):[];return{id:t(),name:s,trigger:c,procedure:a,...h.length>0?{tags:h}:{},version:1,createdAt:e().toISOString(),...n.sourceEpisodeId?{sourceEpisodeId:n.sourceEpisodeId}:{}}}var l=require("node:crypto");function v(n){let e=n?(0,l.createPrivateKey)(n):(0,l.generateKeyPairSync)("ed25519").privateKey,r=(0,l.createPublicKey)(e).export({type:"spki",format:"pem"}).toString(),i=e.export({type:"pkcs8",format:"pem"}).toString();return{publicKeyPem:r,privateKeyPem:i,sign(o){return(0,l.sign)(null,Buffer.from(o,"utf8"),e).toString("base64")}}}function E(n,e,t){try{let r=(0,l.createPublicKey)(t);return(0,l.verify)(null,Buffer.from(n,"utf8"),r,Buffer.from(e,"base64"))}catch{return!1}}function I(n,e){return typeof n.signature!="string"||n.signature.length===0?!1:E(g(n),n.signature,e)}var d=require("node:fs/promises"),f=require("node:path"),D=require("node:crypto");var P="episodes.jsonl",T="skills.json";async function B(n){let e;try{e=await(0,d.readFile)(n,"utf8")}catch(r){if(r.code==="ENOENT")return[];throw r}let t=[];for(let r of e.split(`
+`)){let i=r.trim();i&&t.push(JSON.parse(i))}return t}async function U(n,e){try{return JSON.parse(await(0,d.readFile)(n,"utf8"))}catch(t){if(t.code==="ENOENT")return e;throw t}}var b=class n{episodes;skills;dir;complete;signer;minStepsForSkill;now;idGen;constructor(e,t,r){this.episodes=e,this.skills=t,this.dir=r.dir,this.complete=r.complete,this.signer=r.signer,this.minStepsForSkill=r.minStepsForSkill??3,this.now=r.now??(()=>new Date),this.idGen=r.idGen??(()=>(0,D.randomUUID)())}static async create(e={}){let t=[],r=[];e.dir&&(t=await B((0,f.join)(e.dir,P)),r=await U((0,f.join)(e.dir,T),[]));let i=await u.fromEpisodes(t,{...e.maxEpisodes!==void 0?{maxEpisodes:e.maxEpisodes}:{}}),o=await p.fromSkills(r,{...e.maxSkills!==void 0?{maxSkills:e.maxSkills}:{}});return new n(i,o,e)}async onTaskComplete(e){let t=e.summary??await this.deriveSummary(e),r=this.maybeSign({id:this.idGen(),task:e.task,outcome:e.outcome,summary:t,...e.steps&&e.steps.length>0?{steps:e.steps}:{},...e.tags&&e.tags.length>0?{tags:e.tags}:{},createdAt:this.now().toISOString()});await this.episodes.add(r);let i=null;if((e.synthesizeSkill??this.shouldSynthesize(e))&&this.complete){let s={task:e.task,transcript:e.transcript,complete:this.complete,sourceEpisodeId:r.id,now:this.now,idGen:this.idGen},a=await k(s);a&&(i=this.maybeSign({...a,version:this.skills.nextVersion(a.name)}),await this.skills.add(i))}return this.dir&&await this.save(),{episode:r,skill:i}}async augmentContext(e,t={}){let r=t.minScore??.1,i=await this.skills.recall(e,t.maxSkills??3,r),o=await this.episodes.recall(e,t.maxEpisodes??3,r);if(i.length===0&&o.length===0)return"";let s=[];if(i.length>0){s.push("## Skills learned from experience");for(let{skill:a}of i){let c=a.procedure.length>280?a.procedure.slice(0,280)+"\u2026":a.procedure;s.push(`- **${a.name}** \u2014 use when ${a.trigger||"relevant"}
+  ${c.replace(/\n/g,`
+  `)}`)}}if(o.length>0){s.push("## Relevant past experience");for(let{episode:a}of o)s.push(`- [${a.outcome}] ${a.task} \u2014 ${a.summary}`)}return s.join(`
+`)}async save(){if(!this.dir)return;await(0,d.mkdir)(this.dir,{recursive:!0});let e=this.episodes.all().map(t=>JSON.stringify(t)).join(`
+`);await(0,d.writeFile)((0,f.join)(this.dir,P),e?e+`
+`:"","utf8"),await(0,d.writeFile)((0,f.join)(this.dir,T),JSON.stringify(this.skills.all(),null,2)+`
+`,"utf8")}getPublicKeyPem(){return this.signer?.publicKeyPem}shouldSynthesize(e){return e.outcome!=="success"?!1:(e.steps?.length??0)>=this.minStepsForSkill||e.transcript.length>=400}async deriveSummary(e){if(this.complete)try{let r=(await this.complete([{role:"system",content:"Summarize, in 1-2 sentences, what was attempted and what worked or failed. Output only the summary."},{role:"user",content:`TASK: ${e.task}
+OUTCOME: ${e.outcome}
+
+${e.transcript.slice(0,4e3)}`}])).trim();if(r)return r}catch{}return this.heuristicSummary(e)}heuristicSummary(e){let t=e.transcript.split(`
+`).map(o=>o.trim()).filter(o=>o.length>0);if(t.length===0)return`Task "${e.task}" ended: ${e.outcome}.`;let r=t[0]??"",i=t.length>1?t[t.length-1]??"":"";return i&&i!==r?`${r} \u2026 ${i}`:r}maybeSign(e){return this.signer?{...e,signature:this.signer.sign(g(e))}:e}};0&&(module.exports={EpisodicStore,SkillStore,SoulEngine,canonicalPayload,createEd25519Signer,extractJsonObject,synthesizeSkill,verifySignature,verifySoulRecord});

package/dist/soul/index.d.cts

@@ -0,0 +1,138 @@
+interface SoulMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+type SoulCompletion = (messages: SoulMessage[]) => Promise<string>;
+type EpisodeOutcome = "success" | "failure" | "partial";
+interface Episode {
+    id: string;
+    task: string;
+    outcome: EpisodeOutcome;
+    summary: string;
+    steps?: string[];
+    tags?: string[];
+    createdAt: string;
+    signature?: string;
+}
+interface Skill {
+    id: string;
+    name: string;
+    trigger: string;
+    procedure: string;
+    tags?: string[];
+    version: number;
+    createdAt: string;
+    sourceEpisodeId?: string;
+    signature?: string;
+}
+interface RecalledEpisode {
+    episode: Episode;
+    score: number;
+}
+interface RecalledSkill {
+    skill: Skill;
+    score: number;
+}
+interface EpisodicStoreOptions {
+    maxEpisodes?: number;
+}
+declare class EpisodicStore {
+    private readonly index;
+    private readonly byId;
+    constructor(options?: EpisodicStoreOptions);
+    add(episode: Episode): Promise<void>;
+    recall(query: string, topK?: number, minScore?: number): Promise<RecalledEpisode[]>;
+    get(id: string): Episode | undefined;
+    all(): Episode[];
+    get size(): number;
+    toJSON(): Episode[];
+    static fromEpisodes(episodes: Episode[], options?: EpisodicStoreOptions): Promise<EpisodicStore>;
+}
+interface SkillStoreOptions {
+    maxSkills?: number;
+}
+declare class SkillStore {
+    private readonly index;
+    private readonly byId;
+    constructor(options?: SkillStoreOptions);
+    add(skill: Skill): Promise<void>;
+    recall(query: string, topK?: number, minScore?: number): Promise<RecalledSkill[]>;
+    nextVersion(name: string): number;
+    get(id: string): Skill | undefined;
+    all(): Skill[];
+    get size(): number;
+    toJSON(): Skill[];
+    static fromSkills(skills: Skill[], options?: SkillStoreOptions): Promise<SkillStore>;
+}
+interface SynthesizeSkillInput {
+    task: string;
+    transcript: string;
+    complete: SoulCompletion;
+    sourceEpisodeId?: string;
+    now?: () => Date;
+    idGen?: () => string;
+}
+declare function synthesizeSkill(input: SynthesizeSkillInput): Promise<Skill | null>;
+declare function extractJsonObject(text: string): Record<string, unknown> | null;
+declare function canonicalPayload(record: Record<string, unknown>): string;
+interface SoulSigner {
+    sign(payload: string): string;
+    readonly publicKeyPem: string;
+}
+interface ExportableSoulSigner extends SoulSigner {
+    readonly privateKeyPem: string;
+}
+declare function createEd25519Signer(privateKeyPem?: string): ExportableSoulSigner;
+declare function verifySignature(payload: string, signatureB64: string, publicKeyPem: string): boolean;
+declare function verifySoulRecord(record: Record<string, unknown> & {
+    signature?: string;
+}, publicKeyPem: string): boolean;
+interface SoulEngineOptions {
+    dir?: string;
+    complete?: SoulCompletion;
+    signer?: SoulSigner;
+    minStepsForSkill?: number;
+    maxEpisodes?: number;
+    maxSkills?: number;
+    now?: () => Date;
+    idGen?: () => string;
+}
+interface OnTaskCompleteInput {
+    task: string;
+    transcript: string;
+    outcome: EpisodeOutcome;
+    steps?: string[];
+    tags?: string[];
+    summary?: string;
+    synthesizeSkill?: boolean;
+}
+interface OnTaskCompleteResult {
+    episode: Episode;
+    skill: Skill | null;
+}
+interface AugmentContextOptions {
+    maxSkills?: number;
+    maxEpisodes?: number;
+    minScore?: number;
+}
+declare class SoulEngine {
+    readonly episodes: EpisodicStore;
+    readonly skills: SkillStore;
+    private readonly dir?;
+    private readonly complete?;
+    private readonly signer?;
+    private readonly minStepsForSkill;
+    private readonly now;
+    private readonly idGen;
+    private constructor();
+    static create(options?: SoulEngineOptions): Promise<SoulEngine>;
+    onTaskComplete(input: OnTaskCompleteInput): Promise<OnTaskCompleteResult>;
+    augmentContext(query: string, options?: AugmentContextOptions): Promise<string>;
+    save(): Promise<void>;
+    getPublicKeyPem(): string | undefined;
+    private shouldSynthesize;
+    private deriveSummary;
+    private heuristicSummary;
+    private maybeSign;
+}
+export { type AugmentContextOptions, type Episode, type EpisodeOutcome, EpisodicStore, type EpisodicStoreOptions, type ExportableSoulSigner, type OnTaskCompleteInput, type OnTaskCompleteResult, type RecalledEpisode, type RecalledSkill, type Skill, SkillStore, type SkillStoreOptions, type SoulCompletion, SoulEngine, type SoulEngineOptions, type SoulMessage, type SoulSigner, type SynthesizeSkillInput, canonicalPayload, createEd25519Signer, extractJsonObject, synthesizeSkill, verifySignature, verifySoulRecord };

package/dist/soul/index.d.ts

@@ -0,0 +1,138 @@
+interface SoulMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+type SoulCompletion = (messages: SoulMessage[]) => Promise<string>;
+type EpisodeOutcome = "success" | "failure" | "partial";
+interface Episode {
+    id: string;
+    task: string;
+    outcome: EpisodeOutcome;
+    summary: string;
+    steps?: string[];
+    tags?: string[];
+    createdAt: string;
+    signature?: string;
+}
+interface Skill {
+    id: string;
+    name: string;
+    trigger: string;
+    procedure: string;
+    tags?: string[];
+    version: number;
+    createdAt: string;
+    sourceEpisodeId?: string;
+    signature?: string;
+}
+interface RecalledEpisode {
+    episode: Episode;
+    score: number;
+}
+interface RecalledSkill {
+    skill: Skill;
+    score: number;
+}
+interface EpisodicStoreOptions {
+    maxEpisodes?: number;
+}
+declare class EpisodicStore {
+    private readonly index;
+    private readonly byId;
+    constructor(options?: EpisodicStoreOptions);
+    add(episode: Episode): Promise<void>;
+    recall(query: string, topK?: number, minScore?: number): Promise<RecalledEpisode[]>;
+    get(id: string): Episode | undefined;
+    all(): Episode[];
+    get size(): number;
+    toJSON(): Episode[];
+    static fromEpisodes(episodes: Episode[], options?: EpisodicStoreOptions): Promise<EpisodicStore>;
+}
+interface SkillStoreOptions {
+    maxSkills?: number;
+}
+declare class SkillStore {
+    private readonly index;
+    private readonly byId;
+    constructor(options?: SkillStoreOptions);
+    add(skill: Skill): Promise<void>;
+    recall(query: string, topK?: number, minScore?: number): Promise<RecalledSkill[]>;
+    nextVersion(name: string): number;
+    get(id: string): Skill | undefined;
+    all(): Skill[];
+    get size(): number;
+    toJSON(): Skill[];
+    static fromSkills(skills: Skill[], options?: SkillStoreOptions): Promise<SkillStore>;
+}
+interface SynthesizeSkillInput {
+    task: string;
+    transcript: string;
+    complete: SoulCompletion;
+    sourceEpisodeId?: string;
+    now?: () => Date;
+    idGen?: () => string;
+}
+declare function synthesizeSkill(input: SynthesizeSkillInput): Promise<Skill | null>;
+declare function extractJsonObject(text: string): Record<string, unknown> | null;
+declare function canonicalPayload(record: Record<string, unknown>): string;
+interface SoulSigner {
+    sign(payload: string): string;
+    readonly publicKeyPem: string;
+}
+interface ExportableSoulSigner extends SoulSigner {
+    readonly privateKeyPem: string;
+}
+declare function createEd25519Signer(privateKeyPem?: string): ExportableSoulSigner;
+declare function verifySignature(payload: string, signatureB64: string, publicKeyPem: string): boolean;
+declare function verifySoulRecord(record: Record<string, unknown> & {
+    signature?: string;
+}, publicKeyPem: string): boolean;
+interface SoulEngineOptions {
+    dir?: string;
+    complete?: SoulCompletion;
+    signer?: SoulSigner;
+    minStepsForSkill?: number;
+    maxEpisodes?: number;
+    maxSkills?: number;
+    now?: () => Date;
+    idGen?: () => string;
+}
+interface OnTaskCompleteInput {
+    task: string;
+    transcript: string;
+    outcome: EpisodeOutcome;
+    steps?: string[];
+    tags?: string[];
+    summary?: string;
+    synthesizeSkill?: boolean;
+}
+interface OnTaskCompleteResult {
+    episode: Episode;
+    skill: Skill | null;
+}
+interface AugmentContextOptions {
+    maxSkills?: number;
+    maxEpisodes?: number;
+    minScore?: number;
+}
+declare class SoulEngine {
+    readonly episodes: EpisodicStore;
+    readonly skills: SkillStore;
+    private readonly dir?;
+    private readonly complete?;
+    private readonly signer?;
+    private readonly minStepsForSkill;
+    private readonly now;
+    private readonly idGen;
+    private constructor();
+    static create(options?: SoulEngineOptions): Promise<SoulEngine>;
+    onTaskComplete(input: OnTaskCompleteInput): Promise<OnTaskCompleteResult>;
+    augmentContext(query: string, options?: AugmentContextOptions): Promise<string>;
+    save(): Promise<void>;
+    getPublicKeyPem(): string | undefined;
+    private shouldSynthesize;
+    private deriveSummary;
+    private heuristicSummary;
+    private maybeSign;
+}
+export { type AugmentContextOptions, type Episode, type EpisodeOutcome, EpisodicStore, type EpisodicStoreOptions, type ExportableSoulSigner, type OnTaskCompleteInput, type OnTaskCompleteResult, type RecalledEpisode, type RecalledSkill, type Skill, SkillStore, type SkillStoreOptions, type SoulCompletion, SoulEngine, type SoulEngineOptions, type SoulMessage, type SoulSigner, type SynthesizeSkillInput, canonicalPayload, createEd25519Signer, extractJsonObject, synthesizeSkill, verifySignature, verifySoulRecord };