@plico-ai/sdk 0.0.0-reserved.0 → 0.1.0

package/NOTICE

@@ -0,0 +1,4 @@
+Plico
+Copyright 2026 Plico contributors
+
+This product includes software developed by the Plico contributors.

package/README.md

@@ -1,6 +1,35 @@
 # @plico-ai/sdk
 
-defineTool and defineConfig for Plico projects.
+Typed helpers for writing a Plico project. Both return their argument unchanged; they exist so your editor can check the file.
 
-This is a pre-release placeholder. The first developer preview is in progress at
-https://github.com/ITZSHOAIB/plico. Docs: https://plico.sohab.dev
+```ts
+// plico.config.ts
+import { defineConfig } from "@plico-ai/sdk";
+
+export default defineConfig({ schemaVersion: 1, name: "Support Agent", template: "internal-ops" });
+```
+
+```ts
+// tools/create-ticket.tool.ts
+import { defineTool } from "@plico-ai/sdk";
+
+export default defineTool({
+  name: "create_ticket",
+  description: "Create a support ticket.",
+  inputSchema: {
+    type: "object",
+    properties: { title: { type: "string" } },
+    required: ["title"],
+  },
+  capabilities: ["ticket:write"],
+  approval: { required: false },
+  handler: async (input) => ({ created: input.title }), // input: { title: string }
+});
+```
+
+`defineTool` infers the handler `input` from `inputSchema`:
+
+- A JSON Schema is read for `type`, `enum`, `const`, `properties`, `required` and `items`. Any other keyword makes that part `unknown`; it never becomes a type error.
+- A Zod schema (3 or 4) gives its parsed output type. Add `zod` to your project to use one.
+
+You do not need to install `@plico-ai/sdk` in the project. `plico validate` and `plico run` resolve it from the project when it is there, and fall back to the copy that comes with the CLI. Install it when you want editor types.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { ProjectConfig, ProviderInput, ToolApprovalPolicy, ToolDefinition, ToolHandlerContext } from "@plico-ai/contracts";
+import type { InferToolInput, SchemaInput } from "./infer.js";
+export type { ProjectConfig, ProviderInput, ToolApprovalPolicy, ToolArtifactContext, ToolDefinition, ToolHandlerContext, } from "@plico-ai/contracts";
+export type { InferToolInput } from "./infer.js";
+/** A tool as written in `tools/*.tool.ts`, with the handler input typed from `inputSchema`. */
+export interface ToolSpec<Schema extends SchemaInput> {
+    name: string;
+    description: string;
+    inputSchema: Schema;
+    capabilities: string[];
+    approval: ToolApprovalPolicy;
+    handler: (input: InferToolInput<Schema>, context: ToolHandlerContext) => unknown;
+}
+/** Declare a tool. Returns the object unchanged; the types infer `input` from `inputSchema`. */
+export declare function defineTool<const Schema extends SchemaInput>(tool: ToolSpec<Schema>): ToolDefinition;
+/** Declare `plico.config.ts`. Returns the object unchanged; the types check it. */
+export declare function defineConfig(config: ProjectConfig): ProjectConfig;
+/**
+ * Declare `providers/<name>.ts`: a function that returns any AI SDK language model. Returns the
+ * function unchanged. Plico wraps the model behind its own model port.
+ */
+export declare function defineProvider(provider: (input: ProviderInput) => unknown): (input: ProviderInput) => unknown;

package/dist/index.js

@@ -0,0 +1,15 @@
+/** Declare a tool. Returns the object unchanged; the types infer `input` from `inputSchema`. */
+export function defineTool(tool) {
+    return tool;
+}
+/** Declare `plico.config.ts`. Returns the object unchanged; the types check it. */
+export function defineConfig(config) {
+    return config;
+}
+/**
+ * Declare `providers/<name>.ts`: a function that returns any AI SDK language model. Returns the
+ * function unchanged. Plico wraps the model behind its own model port.
+ */
+export function defineProvider(provider) {
+    return provider;
+}

package/dist/infer.d.ts

@@ -0,0 +1,55 @@
+import type { ZodInputSchema } from "@plico-ai/contracts";
+/** JSON Schema as written in a tool file: `const` inference makes its arrays readonly. */
+export type ReadonlyJson = string | number | boolean | null | readonly ReadonlyJson[] | {
+    readonly [keyword: string]: ReadonlyJson | undefined;
+};
+export type SchemaInput = boolean | ZodInputSchema | {
+    readonly [keyword: string]: ReadonlyJson | undefined;
+};
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type RequiredKeys<S> = S extends {
+    required: readonly (infer R)[];
+} ? R & string : never;
+type InferObject<S> = S extends {
+    properties: infer P;
+} ? Simplify<{
+    [K in keyof P & RequiredKeys<S>]: InferJsonSchema<P[K]>;
+} & {
+    [K in Exclude<keyof P, RequiredKeys<S>>]?: InferJsonSchema<P[K]>;
+}> : Record<string, unknown>;
+/**
+ * The TypeScript type of a JSON Schema value, for the keywords tools use most: `type`, `enum`,
+ * `const`, `properties`, `required` and `items`. Anything else is `unknown`, never an error.
+ */
+export type InferJsonSchema<S> = S extends {
+    const: infer C;
+} ? C : S extends {
+    enum: readonly (infer E)[];
+} ? E : S extends {
+    type: "string";
+} ? string : S extends {
+    type: "number" | "integer";
+} ? number : S extends {
+    type: "boolean";
+} ? boolean : S extends {
+    type: "null";
+} ? null : S extends {
+    type: "array";
+    items: infer Item;
+} ? InferJsonSchema<Item>[] : S extends {
+    type: "array";
+} ? unknown[] : S extends {
+    type: "object";
+} ? InferObject<S> : unknown;
+type InferZod<S> = S extends {
+    safeParseAsync(input: unknown): Promise<infer Result>;
+} ? Extract<Result, {
+    success: true;
+}> extends {
+    data: infer Data;
+} ? Data : unknown : unknown;
+/** The input a tool handler receives, from either a Zod schema or a JSON Schema. */
+export type InferToolInput<S> = S extends ZodInputSchema ? InferZod<S> : InferJsonSchema<S>;
+export {};

package/dist/infer.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,21 +1,45 @@
 {
   "name": "@plico-ai/sdk",
-  "version": "0.0.0-reserved.0",
-  "description": "defineTool and defineConfig for Plico projects. Not released yet.",
+  "version": "0.1.0",
+  "description": "Typed helpers for writing Plico projects: defineConfig and defineTool",
   "license": "Apache-2.0",
   "homepage": "https://plico.sohab.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ITZSHOAIB/plico.git"
+    "url": "git+https://github.com/ITZSHOAIB/plico.git",
+    "directory": "packages/sdk"
   },
   "keywords": [
     "plico",
-    "agent"
-  ],
-  "files": [
-    "README.md"
+    "agent",
+    "typescript",
+    "authoring"
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "NOTICE",
+    "dist"
+  ],
+  "dependencies": {
+    "@plico-ai/contracts": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "test": "vitest run"
   }
-}
+}