palpal-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naruhide KITADA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,114 @@
+# palpal-core (日本語)
+
+`palpal-core` は、安全性を重視した OpenAI Agents SDK 互換（TypeScript）の npm ライブラリです。
+Agents SDK の使い勝手を保ちながら、MCP / Skills / Tool 実行の実運用向け安全制御を追加します。
+
+## 位置づけ
+
+- OpenAI Agents SDK 互換I/Fを維持し、移行コストを最小化
+- `SafetyAgent + Guardrails + Approval flow` による Safety-first 実行モデル
+- MCP / Skills を「実行前」に防御しやすい設計
+
+## 何を解決するか
+
+現在のエージェント実装では、次の課題が起きやすいです。
+
+- MCP/Tools の実行前安全判定が実装依存になりやすい
+- Skills (`SKILL.md`) をそのまま実行可能な Tool として扱いにくい
+- 人間承認が必要な処理の「中断 -> 再開」制御が分散しやすい
+- Chat Completions 互換モデル（Ollama など）を統一I/Fで扱いにくい
+
+`palpal-core` はこれを、`SafetyAgent + Guardrails + Approval flow` で最小差分に統合します。
+
+## 設計のポイント
+
+- Agents SDK 互換I/F:
+  - `new Agent(...)`
+  - `run(agent, input, options?)`
+  - `tool(...)`, `hostedMcpTool(...)`
+- SafetyAgent:
+  - `runner.run(agent, ...)` 時に `Agent` から Skills/MCP/Tools を自動抽出
+  - Go/No-Go/needs_human を fail-closed で判定
+- ModelSafetyAgent:
+  - model + rubric（箇条書き文字列）で判定器を構成
+  - 対象 `Agent` の tool/skill/MCP 文脈を入力に含める
+  - 構造化出力（`allow|deny|needs_human`）で安定判定
+  - 既定は `includeUserIntent: false`（生のユーザー入力は含めない）
+- OpenAI Agents SDK の一般ガードレール併用:
+  - `agent.guardrails.input/tool/output` を追加
+  - `SafetyAgent` とは独立に deny できる二重防御
+- Skills:
+  - `loadSkills(...) -> Skill[]`
+  - `toTools(skills)` で function tools 化
+  - `listSkills` / `describeSkill` / `toIntrospectionTools`
+- Provider:
+  - `getProvider("ollama").getModel("gpt-oss-20b")`
+  - OpenAI / Ollama / LM Studio / Gemini / Anthropic / OpenRouter
+
+## インストール
+
+```bash
+npm install palpal-core
+```
+
+## 最小例
+
+```ts
+import {
+  Agent,
+  SafetyAgent,
+  createRunner,
+  tool,
+  getProvider
+} from "palpal-core";
+
+const runner = createRunner({
+  safetyAgent: new SafetyAgent(async (_agent, request) => {
+    if (request.tool_kind === "mcp") {
+      return { decision: "needs_human", reason: "MCP review required", risk_level: 4 };
+    }
+    return { decision: "allow", reason: "safe", risk_level: 1 };
+  })
+});
+
+const agent = new Agent({
+  name: "assistant",
+  instructions: "be helpful",
+  model: getProvider("ollama").getModel("gpt-oss-20b"),
+  tools: [
+    tool({
+      name: "echo",
+      description: "echo text",
+      execute: async (args) => args
+    })
+  ],
+  guardrails: {
+    input: [
+      ({ inputText }) => ({
+        allow: !inputText.includes("forbidden"),
+        reason: "forbidden input"
+      })
+    ]
+  }
+});
+
+const result = await runner.run(agent, "hello", {
+  extensions: {
+    toolCalls: [{ toolName: "echo", args: { text: "hello" } }]
+  }
+});
+```
+
+## MCP/Skills を防御しやすい理由
+
+- SafetyAgent は実行対象 `Agent` から能力情報を自動取得するため、判定コンテキストの漏れを減らせる
+- Guardrails を入力/ツール/出力で分離でき、禁止条件を短く保てる
+- `needs_human` の承認トークンで、中断処理を安全に再開できる
+
+## チュートリアル
+
+- 日本語: [tutorials/ja/getting-started.md](./tutorials/ja/getting-started.md)
+- 英語: [tutorials/en/getting-started.md](./tutorials/en/getting-started.md)
+- Filesystem MCP + SafetyAgent サンプル: [tutorials/samples/filesystem-mcp-safety.ts](./tutorials/samples/filesystem-mcp-safety.ts)
+- ModelSafetyAgent サンプル: [tutorials/samples/model-safety-agent.ts](./tutorials/samples/model-safety-agent.ts)
+

package/README.md

@@ -0,0 +1,118 @@
+# palpal-core
+
+`palpal-core` is a high-safety, OpenAI Agents SDK-compatible npm library for TypeScript.
+It keeps the familiar Agents SDK style while adding practical runtime safety controls for MCP, Skills, and tool execution.
+
+## Positioning
+
+- OpenAI Agents SDK-compatible interface with minimal migration cost
+- Safety-first execution model (`SafetyAgent + Guardrails + Approval flow`)
+- Designed to make MCP/Skills easier to defend before execution
+
+## What problems it solves
+
+In many current agent stacks:
+
+- MCP/tool safety checks are inconsistent or ad-hoc
+- Skills (`SKILL.md`) are hard to expose as executable tools
+- Human approval flows (`pause -> resume`) are fragmented
+- Chat Completions compatible backends are not unified
+
+`palpal-core` addresses this with a single execution layer:
+`SafetyAgent + Guardrails + Approval flow`.
+
+## Design highlights
+
+- Agents SDK-like interface:
+  - `new Agent(...)`
+  - `run(agent, input, options?)`
+  - `tool(...)`, `hostedMcpTool(...)`
+- `SafetyAgent`:
+  - derives Skills/MCP/Tools from the `Agent` at `runner.run(...)`
+  - fail-closed Go/No-Go/needs_human decision
+- `ModelSafetyAgent`:
+  - accepts a model + rubric (bullet-string rules)
+  - evaluates tool/skill/MCP context from the target `Agent`
+  - returns stable structured decision (`allow|deny|needs_human`)
+  - defaults to `includeUserIntent: false` (raw user input is excluded)
+- MCP approval policy:
+  - `hostedMcpTool(..., { requireApproval: true })` forces `needs_human` before execution
+- General guardrails (OpenAI Agents SDK style) are also supported:
+  - `agent.guardrails.input/tool/output`
+  - independent deny path in addition to `SafetyAgent`
+- Skills:
+  - `loadSkills(...) -> Skill[]`
+  - `toTools(skills)` for function-tool conversion
+  - `listSkills` / `describeSkill` / `toIntrospectionTools`
+- Providers:
+  - `getProvider("ollama").getModel("gpt-oss-20b")`
+  - OpenAI / Ollama / LM Studio / Gemini / Anthropic / OpenRouter
+
+## Install
+
+```bash
+npm install palpal-core
+```
+
+## Minimal example
+
+```ts
+import {
+  Agent,
+  SafetyAgent,
+  createRunner,
+  tool,
+  getProvider
+} from "palpal-core";
+
+const runner = createRunner({
+  safetyAgent: new SafetyAgent(async (_agent, request) => {
+    if (request.tool_kind === "mcp") {
+      return { decision: "needs_human", reason: "MCP review required", risk_level: 4 };
+    }
+    return { decision: "allow", reason: "safe", risk_level: 1 };
+  })
+});
+
+const agent = new Agent({
+  name: "assistant",
+  instructions: "be helpful",
+  model: getProvider("ollama").getModel("gpt-oss-20b"),
+  tools: [
+    tool({
+      name: "echo",
+      description: "echo text",
+      execute: async (args) => args
+    })
+  ],
+  guardrails: {
+    input: [
+      ({ inputText }) => ({
+        allow: !inputText.includes("forbidden"),
+        reason: "forbidden input"
+      })
+    ]
+  }
+});
+
+const result = await runner.run(agent, "hello", {
+  extensions: {
+    toolCalls: [{ toolName: "echo", args: { text: "hello" } }]
+  }
+});
+```
+
+## Why MCP/Skills are easier to defend
+
+- `SafetyAgent` evaluates with capability snapshot derived from the actual `Agent`
+- guardrails are split by stage (`input/tool/output`) for concise policy rules
+- `needs_human` supports explicit approval and safe resume
+
+## Docs
+
+- Japanese README: [README.ja.md](./README.ja.md)
+- Japanese tutorial: [tutorials/ja/getting-started.md](./tutorials/ja/getting-started.md)
+- English tutorial: [tutorials/en/getting-started.md](./tutorials/en/getting-started.md)
+- Filesystem MCP + SafetyAgent sample: [tutorials/samples/filesystem-mcp-safety.ts](./tutorials/samples/filesystem-mcp-safety.ts)
+- ModelSafetyAgent sample: [tutorials/samples/model-safety-agent.ts](./tutorials/samples/model-safety-agent.ts)
+

package/dist/src/agent.d.ts

@@ -0,0 +1,16 @@
+import { AgentGuardrails, AgentLike, Model, Tool } from "./types";
+export interface AgentOptions {
+    name: string;
+    instructions: string;
+    tools?: Tool[];
+    model?: Model;
+    guardrails?: AgentGuardrails;
+}
+export declare class Agent implements AgentLike {
+    readonly name: string;
+    readonly instructions: string;
+    readonly tools: Tool[];
+    readonly model?: Model;
+    readonly guardrails?: AgentGuardrails;
+    constructor(options: AgentOptions);
+}

package/dist/src/agent.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const errors_1 = require("./errors");
+class Agent {
+    name;
+    instructions;
+    tools;
+    model;
+    guardrails;
+    constructor(options) {
+        (0, errors_1.ensure)(options.name?.trim(), "AGENTS-E-RUNNER-CONFIG", "Agent.name is required.");
+        (0, errors_1.ensure)(options.instructions?.trim(), "AGENTS-E-RUNNER-CONFIG", "Agent.instructions is required.");
+        this.name = options.name;
+        this.instructions = options.instructions;
+        this.tools = options.tools ? [...options.tools] : [];
+        this.model = options.model;
+        this.guardrails = options.guardrails;
+    }
+}
+exports.Agent = Agent;

package/dist/src/approval.d.ts

@@ -0,0 +1,14 @@
+import { GateDecision, HumanApprovalRequest, ResumeToken } from "./types";
+export declare class ApprovalController {
+    private readonly approvals;
+    private readonly tokens;
+    private readonly ttlSec;
+    constructor(ttlSec?: number);
+    createApprovalRequest(runId: string, gateDecision: GateDecision, prompt: string): Promise<HumanApprovalRequest>;
+    getPendingApprovals(runId?: string): Promise<HumanApprovalRequest[]>;
+    submitApproval(approvalId: string, decision: "approve" | "deny", comment?: string): Promise<ResumeToken>;
+    consumeResumeToken(runId: string, tokenValue: string): {
+        decision: "approve" | "deny";
+        approvalId: string;
+    };
+}

package/dist/src/approval.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalController = void 0;
+const errors_1 = require("./errors");
+class ApprovalController {
+    approvals = new Map();
+    tokens = new Map();
+    ttlSec;
+    constructor(ttlSec = 900) {
+        this.ttlSec = ttlSec;
+    }
+    async createApprovalRequest(runId, gateDecision, prompt) {
+        (0, errors_1.ensure)(runId, "AGENTS-E-APPROVAL-INVALID", "runId is required.");
+        (0, errors_1.ensure)(gateDecision.decision === "needs_human", "AGENTS-E-APPROVAL-INVALID", "createApprovalRequest requires decision=needs_human.");
+        const approval = {
+            approval_id: gateDecision.approval_id ?? (0, errors_1.createId)("approval"),
+            run_id: runId,
+            required_action: "human_review",
+            prompt,
+            status: "pending"
+        };
+        this.approvals.set(approval.approval_id, { request: approval });
+        return approval;
+    }
+    async getPendingApprovals(runId) {
+        const items = [...this.approvals.values()]
+            .map((record) => record.request)
+            .filter((request) => request.status === "pending");
+        if (!runId) {
+            return items;
+        }
+        return items.filter((item) => item.run_id === runId);
+    }
+    async submitApproval(approvalId, decision, comment) {
+        const record = this.approvals.get(approvalId);
+        (0, errors_1.ensure)(record, "AGENTS-E-APPROVAL-NOT-FOUND", `Approval not found: ${approvalId}`);
+        (0, errors_1.ensure)(record.request.status === "pending", "AGENTS-E-APPROVAL-INVALID", `Approval is not pending: ${approvalId}`);
+        record.request.status = decision === "approve" ? "approved" : "denied";
+        record.comment = comment;
+        const expiresAt = new Date(Date.now() + this.ttlSec * 1000).toISOString();
+        const token = {
+            token: (0, errors_1.createId)("resume"),
+            run_id: record.request.run_id,
+            expires_at: expiresAt,
+            status: "active"
+        };
+        this.tokens.set(token.token, {
+            token,
+            approvalId,
+            decision
+        });
+        return token;
+    }
+    consumeResumeToken(runId, tokenValue) {
+        const tokenRecord = this.tokens.get(tokenValue);
+        (0, errors_1.ensure)(tokenRecord, "AGENTS-E-RESUME-TOKEN", "Resume token is not found.");
+        (0, errors_1.ensure)(tokenRecord.token.run_id === runId, "AGENTS-E-RESUME-TOKEN", "runId mismatch.");
+        (0, errors_1.ensure)(tokenRecord.token.status === "active", "AGENTS-E-RESUME-TOKEN", "Token is not active.");
+        (0, errors_1.ensure)(new Date(tokenRecord.token.expires_at).getTime() > Date.now(), "AGENTS-E-RESUME-TOKEN", "Token has expired.");
+        tokenRecord.token.status = "used";
+        return {
+            decision: tokenRecord.decision,
+            approvalId: tokenRecord.approvalId
+        };
+    }
+}
+exports.ApprovalController = ApprovalController;

package/dist/src/errors.d.ts

@@ -0,0 +1,9 @@
+export type AgentsErrorCategory = "provider" | "safety" | "approval" | "skills" | "mcp" | "runner" | "policy" | "unknown";
+export declare class AgentsError extends Error {
+    readonly code: string;
+    readonly category: AgentsErrorCategory;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+export declare function ensure(condition: unknown, code: string, message: string, details?: unknown): asserts condition;
+export declare function createId(prefix: string): string;

package/dist/src/errors.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentsError = void 0;
+exports.ensure = ensure;
+exports.createId = createId;
+class AgentsError extends Error {
+    code;
+    category;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "AgentsError";
+        this.code = code;
+        this.category = inferErrorCategory(code);
+        this.details = details;
+    }
+}
+exports.AgentsError = AgentsError;
+function ensure(condition, code, message, details) {
+    if (!condition) {
+        throw new AgentsError(code, message, details);
+    }
+}
+function createId(prefix) {
+    const stamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 10);
+    return `${prefix}_${stamp}_${random}`;
+}
+function inferErrorCategory(code) {
+    if (code.includes("PROVIDER")) {
+        return "provider";
+    }
+    if (code.includes("GATE") || code.includes("GUARDRAIL") || code.includes("CAPABILITY")) {
+        return "safety";
+    }
+    if (code.includes("APPROVAL") || code.includes("RESUME")) {
+        return "approval";
+    }
+    if (code.includes("SKILL")) {
+        return "skills";
+    }
+    if (code.includes("MCP")) {
+        return "mcp";
+    }
+    if (code.includes("POLICY")) {
+        return "policy";
+    }
+    if (code.includes("RUNNER") || code.includes("RUN")) {
+        return "runner";
+    }
+    return "unknown";
+}

package/dist/src/guardrails.d.ts

@@ -0,0 +1,11 @@
+import { AgentGuardrails, GuardrailHandler } from "./types";
+export interface StaticGuardrailRule {
+    denyWhen(inputText: string): boolean;
+    reason: string;
+}
+export interface GuardrailsTemplateOptions {
+    inputRules?: StaticGuardrailRule[];
+    outputRules?: StaticGuardrailRule[];
+    toolRules?: GuardrailHandler[];
+}
+export declare function createGuardrailsTemplate(options?: GuardrailsTemplateOptions): AgentGuardrails;

package/dist/src/guardrails.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGuardrailsTemplate = createGuardrailsTemplate;
+function createGuardrailsTemplate(options) {
+    const input = createStaticHandlers(options?.inputRules);
+    const output = createStaticHandlers(options?.outputRules);
+    const tool = options?.toolRules ?? [];
+    return {
+        input: input.length > 0 ? input : undefined,
+        // Tool execution decision should primarily come from SafetyAgent.
+        tool: tool.length > 0 ? tool : undefined,
+        output: output.length > 0 ? output : undefined
+    };
+}
+function createStaticHandlers(rules) {
+    if (!rules || rules.length === 0) {
+        return [];
+    }
+    return rules.map((rule) => {
+        return ({ stage, inputText, finalOutputText }) => {
+            const target = stage === "output" ? finalOutputText ?? "" : inputText;
+            const denied = rule.denyWhen(target);
+            return {
+                allow: !denied,
+                reason: denied ? rule.reason : undefined
+            };
+        };
+    });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./agent";
+export * from "./approval";
+export * from "./errors";
+export * from "./guardrails";
+export * from "./mcp";
+export * from "./providers";
+export * from "./runner";
+export * from "./safety";
+export * from "./skills";
+export * from "./tools";
+export * from "./types";

package/dist/src/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./agent"), exports);
+__exportStar(require("./approval"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./guardrails"), exports);
+__exportStar(require("./mcp"), exports);
+__exportStar(require("./providers"), exports);
+__exportStar(require("./runner"), exports);
+__exportStar(require("./safety"), exports);
+__exportStar(require("./skills"), exports);
+__exportStar(require("./tools"), exports);
+__exportStar(require("./types"), exports);

package/dist/src/mcp.d.ts

@@ -0,0 +1,15 @@
+import { JsonObject, McpCapabilitySummary } from "./types";
+import { HostedMcpServer } from "./tools";
+export interface McpServerConfig extends HostedMcpServer {
+    server_id?: string;
+}
+export interface McpServerHandle {
+    server_id: string;
+    capabilities: McpCapabilitySummary[];
+}
+export declare class McpGateway {
+    private readonly servers;
+    register(config: McpServerConfig): Promise<McpServerHandle>;
+    introspect(serverId: string): Promise<McpCapabilitySummary[]>;
+    call(serverId: string, toolName: string, args: JsonObject): Promise<unknown>;
+}

package/dist/src/mcp.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpGateway = void 0;
+const errors_1 = require("./errors");
+class McpGateway {
+    servers = new Map();
+    async register(config) {
+        (0, errors_1.ensure)(config.url, "AGENTS-E-MCP-UNREACHABLE", "MCP server url is required.");
+        const serverId = config.server_id ?? config.id ?? (0, errors_1.createId)("mcp");
+        this.servers.set(serverId, config);
+        const capabilities = await this.introspect(serverId).catch(() => []);
+        return {
+            server_id: serverId,
+            capabilities
+        };
+    }
+    async introspect(serverId) {
+        const server = this.servers.get(serverId);
+        (0, errors_1.ensure)(server, "AGENTS-E-MCP-UNREACHABLE", `MCP server is not registered: ${serverId}`);
+        if (!server.listTools) {
+            return [];
+        }
+        const capabilities = await server.listTools();
+        (0, errors_1.ensure)(Array.isArray(capabilities), "AGENTS-E-MCP-SCHEMA", "MCP tools/list must return an array.");
+        return capabilities;
+    }
+    async call(serverId, toolName, args) {
+        const server = this.servers.get(serverId);
+        (0, errors_1.ensure)(server, "AGENTS-E-MCP-UNREACHABLE", `MCP server is not registered: ${serverId}`);
+        (0, errors_1.ensure)(toolName, "AGENTS-E-MCP-EXEC", "toolName is required.");
+        return server.callTool(toolName, args);
+    }
+}
+exports.McpGateway = McpGateway;

package/dist/src/providers.d.ts

@@ -0,0 +1,2 @@
+import { ProviderHandle, ProviderName } from "./types";
+export declare function getProvider(providerName?: ProviderName): ProviderHandle;