@ziggs-ai/agent-sdk 0.39.0 → 0.40.1

package/CHANGELOG.md

@@ -30,7 +30,13 @@
 
 - Notes kept with an operator key are agent-private artifacts, so they survive a restart and are not announced.
 
-## Unreleased: agent vocabulary and lifecycle (breaking)
+## Unreleased
+
+## 0.40.1
+
+- `createSkillAgent` offers `artifact_record`, `artifact_list`, `artifact_find`, `artifact_share` and `artifact_attach`, so an agent built from instructions can keep its work as artifacts. The file tools that return a storage URL to upload to or fetch from are not offered: the agent has no web tool, and `artifact_record` already takes a file in one call. The set stays fixed in code; instruction text cannot add tools.
+
+## 0.40.0
 
 - `Agent` names the body returned by `createAgent`; decision engines are `ZiggsBrain` and `ClaudeBrain`. See the README migration table.
 - Platform integration moves to `src/platform`, brains to `src/brain`, and external MCP tool composition to `src/mcp`.

package/dist/Agent.d.ts

@@ -76,6 +76,8 @@ export interface AgentOptions {
     description?: string;
     /** Claude-brain system prompt; falls back to `description`. */
     systemPrompt?: string;
+    /** Read trusted role instructions afresh for each wake. Failure stops the wake. */
+    loadSystemPrompt?: () => Promise<string>;
     specialization?: string | null;
     /**
      * strings compared exactly against a request's `match` field.

package/dist/Agent.js

@@ -239,6 +239,7 @@ export class Agent {
             name: resolved.name || null,
             description: resolved.description || 'A helpful assistant',
             systemPrompt: resolved.systemPrompt,
+            loadSystemPrompt: resolved.loadSystemPrompt,
             specialization: resolved.specialization ?? null,
             requestMatchTags: resolved.requestMatchTags,
             tools: resolved.tools || [],
@@ -418,6 +419,7 @@ export class Agent {
                     toolManager: services.toolManager,
                     description: this.options.description,
                     systemPrompt: this.options.systemPrompt,
+                    loadSystemPrompt: this.options.loadSystemPrompt,
                     specialization: this.options.specialization,
                     model: resolveClaudeModel(this.options.model, this.options.services?.llm?.model),
                     anthropicKey: this.options.anthropicKey,

package/dist/brain/ClaudeBrain.d.ts

@@ -32,6 +32,8 @@ export interface ClaudeBrainOptions {
     description: string;
     /** The agent's system prompt. Preferred over `description` for the role block. */
     systemPrompt?: string;
+    /** Failure is fatal for this wake: never run with stale or fallback instructions. */
+    loadSystemPrompt?: () => Promise<string>;
     specialization?: string | null;
     model: string;
     anthropicKey: string;
@@ -95,6 +97,7 @@ export declare class ClaudeBrain implements Brain {
     workflow: Workflow;
     toolManager: ToolManager;
     private rolePrompt;
+    private loadSystemPrompt?;
     private specialization;
     private model;
     private anthropicKey;

package/dist/brain/ClaudeBrain.js

@@ -199,6 +199,7 @@ export class ClaudeBrain {
     workflow;
     toolManager;
     rolePrompt;
+    loadSystemPrompt;
     specialization;
     model;
     anthropicKey;
@@ -232,13 +233,14 @@ export class ClaudeBrain {
         // written before the split still carry the prompt in `description`, so fall
         // back to it rather than silently dropping their role.
         this.rolePrompt = opts.systemPrompt || opts.description;
+        this.loadSystemPrompt = opts.loadSystemPrompt;
         this.specialization = opts.specialization ?? null;
         this.model = opts.model;
         this.anthropicKey = opts.anthropicKey;
         this.operatorKey = opts.operatorKey;
         this.agentId = opts.agentId;
         this.maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
-        this.statelessPerWake = opts.statelessPerWake ?? false;
+        this.statelessPerWake = opts.statelessPerWake ?? !!opts.loadSystemPrompt;
         this.queryFn = opts.queryFn ?? query;
         this.readAgreement = opts.readAgreement ?? ((agreementId) => getAgreement(agreementId, {
             operatorKey: this.operatorKey,
@@ -393,9 +395,16 @@ export class ClaudeBrain {
                 };
             }
         }
+        // Keep it local: different conversation lanes can wake concurrently.
+        // An unavailable/revoked instruction source must not fall back to yesterday's role.
+        const rolePrompt = this.loadSystemPrompt
+            ? await this.loadSystemPrompt()
+            : this.rolePrompt;
+        if (!rolePrompt.trim())
+            throw new Error('Agent instructions are empty');
         const roleBlock = [
             `## Your role`,
-            this.rolePrompt,
+            rolePrompt,
             this.specialization ? `Specialization: ${this.specialization}` : '',
         ].filter(Boolean).join('\n');
         // Two blocks, not one string: the shared protocol first so its cache prefix

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export type { ParsedSkill, SkillFile, SkillReference } from './skills/parseSkill
 export { loadSkill, readSkillFiles, assertSkillHash } from './skills/loadSkill.js';
 export { skillReadReferenceTool } from './skills/skillReadReference.js';
 export { Agent, createAgent, createAgentPool, DEFAULT_MODEL, resolveFleetModel } from './Agent.js';
+export { createSkillAgent } from './skills/createSkillAgent.js';
 export { ZiggsBrain } from './brain/ZiggsBrain.js';
 export { ClaudeBrain } from './brain/ClaudeBrain.js';
 export type { CognitionKind, ClaudeBrainOptions } from './brain/ClaudeBrain.js';

package/dist/index.js

@@ -17,6 +17,7 @@ export { parseSkill, skillHash, skillRolePrompt, skillReferenceName, skillRefere
 export { loadSkill, readSkillFiles, assertSkillHash } from './skills/loadSkill.js';
 export { skillReadReferenceTool } from './skills/skillReadReference.js';
 export { Agent, createAgent, createAgentPool, DEFAULT_MODEL, resolveFleetModel } from './Agent.js';
+export { createSkillAgent } from './skills/createSkillAgent.js';
 export { ZiggsBrain } from './brain/ZiggsBrain.js';
 export { ClaudeBrain } from './brain/ClaudeBrain.js';
 // The exact strings a Claude-brain wake sends: the shared protocol block, the

package/dist/skills/createSkillAgent.d.ts

@@ -0,0 +1,12 @@
+import { type AgentOptions } from '../Agent.js';
+/** The same instructions run on a host or on a person's machine. The trusted
+ * caller supplies bytes; instruction text cannot add tools or runtime options.
+ */
+export declare function createSkillAgent(options: {
+    agentId: string;
+    operatorKey: string;
+    readInstructions: () => Promise<string>;
+    model?: string;
+    anthropicKey?: string;
+    metricsTap?: AgentOptions['metricsTap'];
+}): import("../Agent.js").Agent;

package/dist/skills/createSkillAgent.js

@@ -0,0 +1,41 @@
+import { createAgent } from '../Agent.js';
+import { ARTIFACT_TOOLS } from '../platform/tools/tier2/artifactTools.js';
+import { toolName } from '../tools/defineTool.js';
+import { parseSkill, skillRolePrompt } from './parseSkill.js';
+/** The artifact tools that finish inside one call, so instructions can keep
+ * their work as artifacts. The rest hand back a storage URL to upload to or
+ * fetch from, and this agent has no web tool to do that with.
+ */
+const SKILL_ARTIFACT_TOOL_NAMES = new Set([
+    'artifact_record',
+    'artifact_list',
+    'artifact_find',
+    'artifact_share',
+    'artifact_attach',
+]);
+const SKILL_ARTIFACT_TOOLS = ARTIFACT_TOOLS.filter((tool) => SKILL_ARTIFACT_TOOL_NAMES.has(toolName(tool) ?? ''));
+/** The same instructions run on a host or on a person's machine. The trusted
+ * caller supplies bytes; instruction text cannot add tools or runtime options.
+ */
+export function createSkillAgent(options) {
+    return createAgent({
+        agentId: options.agentId,
+        operatorKey: options.operatorKey,
+        anthropicKey: options.anthropicKey,
+        model: options.model,
+        cognition: 'claude-sdk',
+        description: 'An agent running instructions shared by its owner.',
+        loadSystemPrompt: async () => {
+            const text = await options.readInstructions();
+            const skill = parseSkill([{ path: 'SKILL.md', bytes: Buffer.from(text, 'utf8') }]);
+            return skillRolePrompt(skill);
+        },
+        tools: [...SKILL_ARTIFACT_TOOLS],
+        taskTools: 'all',
+        actsOnHireActivation: true,
+        respondsToProposals: true,
+        metricsTap: options.metricsTap,
+        initial: 'ready',
+        states: { ready: { kind: 'parked', transitions: [] } },
+    });
+}

package/dist/types.d.ts

@@ -590,6 +590,8 @@ export interface DefineAgentInput {
      * relies on. Never surfaced in the store.
      */
     systemPrompt?: string;
+    /** Trusted host callback, read at every wake; never exposed to the model. */
+    loadSystemPrompt?: () => Promise<string>;
     specialization?: string;
     initial: string;
     states: Record<string, State>;
@@ -622,6 +624,7 @@ export interface AgentConfig {
     description: string;
     /** Claude-brain system prompt; falls back to `description`. */
     systemPrompt?: string;
+    loadSystemPrompt?: () => Promise<string>;
     specialization?: string;
     tools: unknown[];
     /** Normalized declared needs — see DefineAgentInput.needs. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -30,7 +30,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.284",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.37.21",
+    "@ziggs-ai/api-client": "0.37.23",
     "@ziggs-ai/contracts": "^0.23.3",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",