esoul-sdk 0.3.0

package/llms.txt

@@ -0,0 +1,23 @@
+# esoul-sdk
+
+> Build ExternalSoul apps: event-sourced state, agent tools on every surface, server ops and webhooks,
+> durable background tasks, OAuth connections held by the platform, files. Apps are built and tested
+> in the Forge workbench, submitted as a pull request, reviewed, released by one script, then added
+> to a workspace like any native app.
+
+- llms-full.txt — the complete contract in one file (read it whole)
+- docs/01-getting-started.md — Getting started
+- docs/02-manifest.md — The manifest — `plugin.json`
+- docs/03-events-and-state.md — Events and state — the heart of the contract
+- docs/04-tools.md — Tools — what agents call
+- docs/05-ui.md — The UI
+- docs/06-server.md — The server half — `server.ts`
+- docs/07-background-tasks.md — Background tasks — durable work
+- docs/08-connections.md — Connections and OAuth — tokens the platform holds for you
+- docs/09-files.md — Files — workspace files, Drive, your own provider
+- docs/10-testing.md — Testing — the fold contract as tests
+- docs/11-shipping.md — Shipping — submit, review, release, install
+- docs/12-rules.md — Rules and failures — every rule with the failure that earned it
+
+The one rule behind the others: events are the truth — pure idempotent processors, ids minted in
+dataCreators, collapse keys on bursts, and an app reaches the platform only through esoul-sdk.

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "esoul-sdk",
+  "version": "0.3.0",
+  "description": "Build ExternalSoul apps: event-sourced state, agent tools, server ops, background tasks, OAuth connections, files — the contract the Forge compiles against.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./llms-full.txt": "./llms-full.txt",
+    "./schemas/plugin.schema.json": "./schemas/plugin.schema.json"
+  },
+  "bin": {
+    "esoul-app": "bin/esoul-plugin.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "schemas",
+    "docs",
+    "scripts/build-llms.mjs",
+    "llms.txt",
+    "llms-full.txt",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "docs:llms": "node scripts/build-llms.mjs",
+    "prepack": "npm run docs:llms && npm run build"
+  },
+  "dependencies": {
+    "zod": "^3.25.0",
+    "nanoid": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-redux": ">=9"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-redux": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "externalsoul",
+    "esoul",
+    "plugin",
+    "sdk",
+    "agent",
+    "event-sourcing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vyomkeshj/ExternalSoul.git",
+    "directory": "packages/esoul-sdk"
+  },
+  "homepage": "https://externalsoul.com",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/plugin.schema.json

@@ -0,0 +1,263 @@
+{
+  "$ref": "#/definitions/PluginManifest",
+  "definitions": {
+    "PluginManifest": {
+      "type": "object",
+      "properties": {
+        "manifestVersion": {
+          "type": "number",
+          "const": 1
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500
+        },
+        "applicationType": {
+          "type": "string",
+          "pattern": "^plugin_[a-z0-9_]*$"
+        },
+        "entry": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9_-]+$"
+        },
+        "icon": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Za-z0-9]*$",
+          "maxLength": 40
+        },
+        "author": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "email": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name"
+          ],
+          "additionalProperties": false
+        },
+        "kickableTasks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        },
+        "webhooks": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "default": []
+        },
+        "ops": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_-]*$"
+          },
+          "default": []
+        },
+        "pollTasks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "task": {
+                "type": "string"
+              },
+              "everyMinutes": {
+                "type": "integer",
+                "minimum": 5,
+                "maximum": 1440
+              }
+            },
+            "required": [
+              "task",
+              "everyMinutes"
+            ],
+            "additionalProperties": false
+          },
+          "default": []
+        },
+        "platformApi": {
+          "type": "object",
+          "properties": {
+            "min": {
+              "type": "string",
+              "pattern": "^\\d+\\.\\d+\\.\\d+$"
+            },
+            "max": {
+              "type": "string",
+              "pattern": "^\\d+\\.\\d+\\.\\d+$"
+            }
+          },
+          "required": [
+            "min"
+          ],
+          "additionalProperties": false
+        },
+        "scopes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        },
+        "workspaceTools": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*:[a-z][a-z0-9_]*$"
+          },
+          "default": []
+        },
+        "connections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "key": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$"
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "oauth2",
+                  "apiKey"
+                ]
+              },
+              "label": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 60
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 300
+              },
+              "authorizeUrl": {
+                "type": "string",
+                "format": "uri"
+              },
+              "tokenUrl": {
+                "type": "string",
+                "format": "uri"
+              },
+              "oauthScopes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "clientIdEnv": {
+                "type": "string",
+                "pattern": "^[A-Z][A-Z0-9_]*$"
+              },
+              "clientSecretEnv": {
+                "type": "string",
+                "pattern": "^[A-Z][A-Z0-9_]*$"
+              },
+              "headerNames": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "key",
+              "kind",
+              "label"
+            ],
+            "additionalProperties": false
+          },
+          "default": []
+        },
+        "fileSources": {
+          "type": "object",
+          "properties": {
+            "workspace": {
+              "type": "string",
+              "enum": [
+                "read",
+                "readwrite"
+              ]
+            },
+            "providers": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$"
+              },
+              "default": []
+            }
+          },
+          "additionalProperties": false
+        },
+        "fileProviders": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "key": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$"
+              },
+              "connectionKey": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$"
+              },
+              "label": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 60
+              }
+            },
+            "required": [
+              "key",
+              "connectionKey",
+              "label"
+            ],
+            "additionalProperties": false
+          },
+          "default": []
+        }
+      },
+      "required": [
+        "manifestVersion",
+        "id",
+        "name",
+        "version",
+        "description",
+        "applicationType",
+        "entry"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/scripts/build-llms.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Regenerate llms.txt (short) and llms-full.txt (the whole contract) from README + docs/,
+ * so a coding model reads exactly what a person reads. `npm run docs:llms`.
+ */
+import { readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const pages = readdirSync(join(root, "docs")).filter((f) => /^\d\d-.*\.md$/.test(f)).sort();
+const full = [
+  "# esoul-sdk — the complete contract for building ExternalSoul apps (llms-full.txt)",
+  "",
+  "Generated from README.md and docs/. Read it whole. Every rule carries the failure that earned it.",
+  "",
+  readFileSync(join(root, "README.md"), "utf8"),
+  ...pages.map((f) => `\n\n${"=".repeat(78)}\n${readFileSync(join(root, "docs", f), "utf8")}`),
+].join("\n");
+writeFileSync(join(root, "llms-full.txt"), full);
+const short = [
+  "# esoul-sdk",
+  "",
+  "> Build ExternalSoul apps: event-sourced state, agent tools on every surface, server ops and webhooks,",
+  "> durable background tasks, OAuth connections held by the platform, files. Apps are built and tested",
+  "> in the Forge workbench, submitted as a pull request, reviewed, released by one script, then added",
+  "> to a workspace like any native app.",
+  "",
+  "- llms-full.txt — the complete contract in one file (read it whole)",
+  ...pages.map((f) => `- docs/${f} — ${readFileSync(join(root, "docs", f), "utf8").split("\n")[0].replace(/^#\s*\d+\.\s*/, "")}`),
+  "",
+  "The one rule behind the others: events are the truth — pure idempotent processors, ids minted in",
+  "dataCreators, collapse keys on bursts, and an app reaches the platform only through esoul-sdk.",
+  "",
+].join("\n");
+writeFileSync(join(root, "llms.txt"), short);
+console.log(`llms-full.txt ${full.length} chars from ${pages.length} pages; llms.txt ${short.length} chars`);