@codenotch/process 0.0.0-dev → 0.1.5

package/README.md

@@ -1,51 +1,51 @@
-# @codenotch/process
-
-The standard library and type surface of Codenotch script processes.
-
-Script processes execute **on the server only**: the engine embeds this package's
-compiled runtime and serves it to `require('@codenotch/process')` inside the V8 workflow
-sandbox. What the package distributes to process authors is the **type declarations**
-(`dist/types`) — there is no client-side execution, and the runtime never ships in a
-process bundle (the deploy bundler treats the package as external).
-
-## Layout
-
-```
-src/lib       the public library: process()/triggers, ctx (Context), errors,
-              Instant, Duration, Decimal, encodings, url, canonicalJson, is, hash.
-              Pure TypeScript; talks to the engine only through the EngineBindings
-              seam (bindings.ts). dist/types is emitted from here.
-src/runtime   the wire-protocol layer: sandbox hardening, the command channel over
-              the __host adapter, and the engine entry points (__start, __deliver,
-              __cancelDeliver, __deliverChildEvent, __processMetadataJson,
-              __concurrencyKey). Engine-internal — never part of the public types.
-src/activity  the '@codenotch/process/activity' entry: activity() and the activity-side
-              types. Ships as runtime JS (dist/activity.mjs) — the deploy bundler
-              inlines it into each activity bundle (activities run on Node).
-src/testing   the '@codenotch/process/testing' entry: the process-test facade
-              (test/expect/env — see doc/reference/process-tests.md). Its bundle
-              (dist/test-prelude.js) is the engine's V8 test-host prelude; the entry
-              distributes types only, like the root.
-```
-
-## Build
-
-`node build.mjs` — type-checks, emits `dist/types` and bundles the three runtimes:
-`src/runtime/prelude.ts` → `dist/prelude.js` (IIFE), `src/activity/index.ts` →
-`dist/activity.mjs`, `src/testing/main.ts` → `dist/test-prelude.js` (IIFE). Output files
-are rewritten only when content changed. The `Echino.Services.Framework.Processes`
-csproj runs this automatically when sources changed and embeds `dist/prelude.js`
-(`ScriptEngine.WorkflowPrelude.js`) and `dist/test-prelude.js`
-(`ScriptEngine.TestPrelude.js`), so the engine and the types can never drift.
-
-`dist/` is committed: a .NET-only checkout builds without running npm as long as the
-TypeScript sources are untouched.
-
-## Rules (doc/reference/process-stdlib.md holds the user-facing docs)
-
-- Every `ctx` method and library function is documented (JSDoc here, reference doc there)
-  and covered by an example-grade fixture in
-  `test/Echino.Services.Framework.Processes.Test/testSchemas/StdlibTests`.
-- Strong typing first, dynamic as fallback (`ctx.call(handle)` over `ctx.call<In, Out>('name')`).
-- The library layer stays pure: anything touching the world goes through the bindings
-  seam and is journaled by the engine.
+# @codenotch/process
+
+The standard library and type surface of Codenotch script processes.
+
+Script processes execute **on the server only**: the engine embeds this package's
+compiled runtime and serves it to `require('@codenotch/process')` inside the V8 workflow
+sandbox. What the package distributes to process authors is the **type declarations**
+(`dist/types`) — there is no client-side execution, and the runtime never ships in a
+process bundle (the deploy bundler treats the package as external).
+
+## Layout
+
+```
+src/lib       the public library: process()/triggers, ctx (Context), errors,
+              Instant, Duration, Decimal, encodings, url, canonicalJson, is, hash.
+              Pure TypeScript; talks to the engine only through the EngineBindings
+              seam (bindings.ts). dist/types is emitted from here.
+src/runtime   the wire-protocol layer: sandbox hardening, the command channel over
+              the __host adapter, and the engine entry points (__start, __deliver,
+              __cancelDeliver, __deliverChildEvent, __processMetadataJson,
+              __concurrencyKey). Engine-internal — never part of the public types.
+src/activity  the '@codenotch/process/activity' entry: activity() and the activity-side
+              types. Ships as runtime JS (dist/activity.mjs) — the deploy bundler
+              inlines it into each activity bundle (activities run on Node).
+src/testing   the '@codenotch/process/testing' entry: the process-test facade
+              (test/expect/env — see doc/reference/process-tests.md). Its bundle
+              (dist/test-prelude.js) is the engine's V8 test-host prelude; the entry
+              distributes types only, like the root.
+```
+
+## Build
+
+`node build.mjs` — type-checks, emits `dist/types` and bundles the three runtimes:
+`src/runtime/prelude.ts` → `dist/prelude.js` (IIFE), `src/activity/index.ts` →
+`dist/activity.mjs`, `src/testing/main.ts` → `dist/test-prelude.js` (IIFE). Output files
+are rewritten only when content changed. The `Echino.Services.Framework.Processes`
+csproj runs this automatically when sources changed and embeds `dist/prelude.js`
+(`ScriptEngine.WorkflowPrelude.js`) and `dist/test-prelude.js`
+(`ScriptEngine.TestPrelude.js`), so the engine and the types can never drift.
+
+`dist/` is committed: a .NET-only checkout builds without running npm as long as the
+TypeScript sources are untouched.
+
+## Rules (doc/reference/process-stdlib.md holds the user-facing docs)
+
+- Every `ctx` method and library function is documented (JSDoc here, reference doc there)
+  and covered by an example-grade fixture in
+  `test/Echino.Services.Framework.Processes.Test/testSchemas/StdlibTests`.
+- Strong typing first, dynamic as fallback (`ctx.call(handle)` over `ctx.call<In, Out>('name')`).
+- The library layer stays pure: anything touching the world goes through the bindings
+  seam and is journaled by the engine.

package/dist/types/lib/connectors.d.ts

@@ -234,9 +234,31 @@ export interface PaymentHandle {
      */
     chargeSavedMethod(request: ChargeRequest, opts?: ActivityOptions): Promise<ChargeResult>;
 }
+/**
+ * A file the model reads: by reference ({ renderingId } — a ctx.render.pdf result works
+ * as-is), the server resolves the bytes at call time and they never travel through the
+ * process; inline bytes ride the journal base64-encoded — keep them small, big documents
+ * belong in renderings. Accepted media types: image/* and application/pdf, each gated on
+ * the bound provider's input capabilities.
+ */
+export type LlmFile = {
+    renderingId: string;
+} | {
+    mediaType: string;
+    bytes: Uint8Array;
+    fileName?: string;
+};
+/** One piece of a message: text, or a file the model reads alongside it. */
+export type LlmContentPart = {
+    type: 'text';
+    text: string;
+} | ({
+    type: 'file';
+} & LlmFile);
 export interface LlmMessage {
     role: 'user' | 'assistant';
-    content: string;
+    /** Plain text, or an ordered part array. File parts belong in user messages. */
+    content: string | LlmContentPart[];
 }
 export interface LlmUsage {
     inputTokens: number;
@@ -246,6 +268,11 @@ export type LlmStopReason = 'end' | 'maxTokens' | 'refusal';
 export interface LlmRequest {
     /** One user message — the simple form. Exactly one of prompt and messages. */
     prompt?: string;
+    /**
+     * Files the model reads with the prompt (they precede it) — prompt-form only; the
+     * messages form places files as content parts.
+     */
+    files?: LlmFile[];
     /** The full conversation, for multi-turn flows the process assembles itself. */
     messages?: LlmMessage[];
     system?: string;

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "@codenotch/process",
-  "version": "0.0.0-dev",
-  "description": "Types and standard library for Codenotch script processes. Processes execute on the server only: the engine embeds the compiled runtime (dist/prelude.js); this package distributes the type declarations.",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/EchinoHub/service-core.git",
-    "directory": "src/codenotch-process"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "types": "./dist/types/lib/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/types/lib/index.d.ts"
-    },
-    "./activity": {
-      "types": "./dist/types/activity/index.d.ts",
-      "default": "./dist/activity.mjs"
-    },
-    "./template": {
-      "types": "./dist/types/template/index.d.ts",
-      "default": "./dist/template.mjs"
-    },
-    "./testing": {
-      "types": "./dist/types/testing/index.d.ts"
-    }
-  },
-  "files": [
-    "dist/types",
-    "dist/activity.mjs",
-    "dist/template.mjs"
-  ],
-  "scripts": {
-    "build": "node build.mjs",
-    "check": "tsc -p tsconfig.json --noEmit"
-  },
-  "devDependencies": {
-    "esbuild": "^0.25.9",
-    "typescript": "^5.9.2"
-  }
-}
+{
+  "name": "@codenotch/process",
+  "version": "0.1.5",
+  "description": "Types and standard library for Codenotch script processes. Processes execute on the server only: the engine embeds the compiled runtime (dist/prelude.js); this package distributes the type declarations.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EchinoHub/service-core.git",
+    "directory": "src/codenotch-process"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/types/lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/lib/index.d.ts"
+    },
+    "./activity": {
+      "types": "./dist/types/activity/index.d.ts",
+      "default": "./dist/activity.mjs"
+    },
+    "./template": {
+      "types": "./dist/types/template/index.d.ts",
+      "default": "./dist/template.mjs"
+    },
+    "./testing": {
+      "types": "./dist/types/testing/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/types",
+    "dist/activity.mjs",
+    "dist/template.mjs"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.9",
+    "typescript": "^5.9.2"
+  }
+}