@jsm-mit/sultana-agent-tools-package 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The tool contract. Deliberately framework-agnostic: the shape matches what OpenAI, Anthropic
+ * and `@jsm-mit/chat-agent-package` all want from a function tool, so wiring this package into an
+ * agent host is registration, not translation.
+ */
+/** A JSON Schema object describing a tool's arguments. Kept loose on purpose — the schema travels
+ * to a model provider verbatim and every provider accepts a slightly different dialect. */
+export interface ToolParametersSchema {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+}
+export type ToolErrorCode = 
+/** The model sent arguments the tool rejected before any canister call. */
+"invalid_arguments"
+/** The named entity is not in this salon. */
+ | "not_found"
+/** The canister refused the caller — wrong identity, or a revoked agent grant. */
+ | "not_authorized"
+/** The daily action quota is spent, or the call was refused at the inspection stage. */
+ | "quota_exceeded"
+/** The canister returned a business error. */
+ | "canister_error"
+/** Transport failure — no reply from the replica. */
+ | "unavailable";
+/**
+ * Every tool returns one of these. **`execute` never throws**: an agent has to be able to read the
+ * failure and ask about it, and a thrown error in a tool-calling loop is either swallowed by the
+ * host or ends the conversation.
+ */
+export type ToolResult = {
+    status: "ok";
+    summary: string;
+    data?: unknown;
+}
+/** The tool made NO canister call. `summary` describes what would happen, built from resolved
+ * arguments (worker names and service-type labels already looked up), and `echo` carries the
+ * exact arguments to send back with `confirmed: true`. */
+ | {
+    status: "confirmation_required";
+    summary: string;
+    echo: Record<string, unknown>;
+} | {
+    status: "error";
+    summary: string;
+    code: ToolErrorCode;
+};
+export interface AgentTool {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: ToolParametersSchema;
+    /** A short Polish line a chat shows while the tool runs — present continuous, ending with "…"
+     * ("Sprawdzam listę usług…"). Never sent to the model. A write tool called with
+     * `confirmed: false` shows the same line: the preview is still work the owner waits for. */
+    readonly progress: string;
+    execute(args: Record<string, unknown>): Promise<ToolResult>;
+}
+export declare function ok(summary: string, data?: unknown): ToolResult;
+export declare function err(code: ToolErrorCode, summary: string): ToolResult;
+export declare function needsConfirmation(summary: string, echo: Record<string, unknown>): ToolResult;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;2FAC2F;AAC3F,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAI/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa;AACrB,2EAA2E;AACzE,mBAAmB;AACrB,6CAA6C;GAC3C,WAAW;AACb,kFAAkF;GAChF,gBAAgB;AAClB,wFAAwF;GACtF,gBAAgB;AAClB,8CAA8C;GAC5C,gBAAgB;AAClB,qDAAqD;GACnD,aAAa,CAAC;AAEpB;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAChB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE;AACnD;;0DAE0D;GACxD;IAAE,MAAM,EAAE,uBAAuB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACnF;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAEhE,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C;;gGAE4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC/D;AAED,wBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAE9D;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAEpE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAE5F"}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * The tool contract. Deliberately framework-agnostic: the shape matches what OpenAI, Anthropic
+ * and `@jsm-mit/chat-agent-package` all want from a function tool, so wiring this package into an
+ * agent host is registration, not translation.
+ */
+export function ok(summary, data) {
+    return data === undefined ? { status: "ok", summary } : { status: "ok", summary, data };
+}
+export function err(code, summary) {
+    return { status: "error", code, summary };
+}
+export function needsConfirmation(summary, echo) {
+    return { status: "confirmation_required", summary, echo };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@jsm-mit/sultana-agent-tools-package",
+    "version": "0.2.0",
+    "description": "Agent tool layer for a Sultana salon: framework-agnostic tools (services, promos, schedule) over the Sultana core canister wrapper, plus a read-only set that needs no identity.",
+    "homepage": "https://github.com/JSM-Sultana/sultana-agent-tools-package#readme",
+    "bugs": {
+        "url": "https://github.com/JSM-Sultana/sultana-agent-tools-package/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/JSM-Sultana/sultana-agent-tools-package.git"
+    },
+    "license": "ISC",
+    "author": "",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist/"
+    ],
+    "scripts": {
+        "build": "tsc && tsc -p tsconfig.tests.json",
+        "clean": "rm -rf dist",
+        "test": "node --import tsx --test \"tests/**/*.test.ts\"",
+        "sandbox": "npx tsx --env-file-if-exists=.env sandbox/main.ts",
+        "prepare": "npm run build",
+        "test-tools": "npx tsx --env-file-if-exists=.env --test tests/integration/test-salon-tools.ts",
+        "whoami": "npx tsx --env-file-if-exists=.env sandbox/whoami.ts",
+        "publish-public": "bash scripts/publish-public.sh"
+    },
+    "dependencies": {
+        "@icp-sdk/core": "^6.1.0",
+        "@jsm-mit/sultana-core-motoko-package": "^0.16.0"
+    },
+    "devDependencies": {
+        "@jsm-mit/utils-package": "^0.5.0",
+        "@types/node": "^25.5.2",
+        "openai": "^4.104.0",
+        "tsx": "^4.18.0",
+        "typescript": "^5.9.3"
+    }
+}