@arnilo/prism 0.0.13 → 0.0.15

package/docs/workflows.md

@@ -18,6 +18,7 @@ Primary exports:
 | `createWorkflowCommands` | Optional `CommandDefinition[]` for direct/background/replay/status/list/cancel/resume and, when selected, schedule control |
 | `enqueueWorkflow` / `startWorkflowBackground` / `createWorkflowCoordinator` | Persist queued work and atomically claim/renew/execute it across processes using `LeaseStore` |
 | `createWorkflowSchedules` | Explicit ownership-scoped one-time/interval/host-calculated schedules over existing checkpoint/lease stores |
+| `createProactiveScheduleCapabilities` | Scoped, expiring, revocable capability tokens that enable proactive schedules; revocation stops firing fail-closed |
 
 Included through `@arnilo/prism-sdk` and `@arnilo/prism-all`; installing either profile does not start workflows. Interactive TUI is out of scope (C-012 deferred).
 
@@ -82,6 +83,8 @@ Every node receives bounded `ctx.state`, `ctx.stateVersion`, and async `ctx.upda
 
 `createWorkflowSchedules({ store, leases, checkpoints, workflows, ownership, ownerId, calculators? })` is inert until its host calls `pollOnce()` or `run({ signal })`. Ownership requires `tenantId` plus `accountId` or `userId`. Methods are `create`, `get`, `list`, `pause`, `resume`, `trigger`, `delete`, `pollOnce`, and `run`. A record has one required `nextRunAt`, optional fixed `intervalMs` or registered `calculatorId` (never both), bounded input/metadata, status, version, and last-fire attribution. Manual trigger requires an idempotency key. Scheduled run IDs derive from schedule ID plus fire timestamp, so retry after enqueue-before-advance finds the same queued checkpoint instead of duplicating it. Defaults: page 100/hard 500, due claims 16/hard 256, input 256 KiB/hard 1 MiB, poll 1s, fire lease 30s.
 
+`createProactiveScheduleCapabilities({ schedules, store, ownership, ownerId, defaultTtlMs?, maxTtlMs?, onCapability? })` wraps a `WorkflowSchedules` facade in explicit user enablement. `enable({ workflowId, scope, actor, nextRunAt, intervalMs?|calculatorId?, input?, ttlMs? })` creates the schedule plus a scoped, expiring `ScheduleCapabilityToken` (default TTL 24h / hard 31d, record ≤ 16 KiB) stamped with redacted actor refs. `revoke(tokenId, actor)` marks the token revoked and pauses the underlying schedule so `pollOnce()` never fires it (fail-closed). `assertActive(tokenId)` is a fail-closed guard for manual trigger paths — it throws on missing/revoked/expired tokens. `onCapability` emits `capability_enabled` / `capability_revoked` / `capability_denied` events (redacted refs only) that hosts bridge to `@arnilo/prism-policy` for an auditable ledger. Tokens are ownership-scoped checkpoint records; no cron expression or secret is persisted.
+
 ## Outputs / response / events
 
 `runWorkflow` / `resumeWorkflow` resolve to `WorkflowRunResult`:
@@ -280,6 +283,7 @@ runRpcServer({
 - Nested workflows inherit host registries/policies and cannot inject broader tools, agents, ownership, or credentials. Nested depth is inherited; child suspension bubbles to the parent review cursor.
 - Replay source ownership/hash/status/node eligibility are checked before a new checkpoint is created. Source records are immutable, lineage is bounded, and copied approval-bearing paths are rejected.
 - Schedule services are ownership-scoped and explicitly started. Per-fire leases plus deterministic run IDs/CAS prevent duplicate enqueue across coordinators and crash retry. Host calculator IDs resolve only from the supplied map; no callback or cron expression is persisted.
+- Proactive schedules require an explicit capability grant. Revocation pauses the schedule (never fired by `pollOnce`) and `assertActive` fails closed on missing/revoked/expired tokens; enable/revoke/deny events carry redacted actor refs for the host policy ledger. Capability TTL is capped (default 24h / hard 31d) and the token record is byte-bounded (≤ 16 KiB); tokens are ownership-scoped, so foreign access fails closed rather than leaking existence.
 - Scheduler stores O(nodes + active outputs + bounded state history); ready-node work uses indegree maps, not repeated full scans.
 - Lease acquisition is atomic; opaque tokens protect renew/release; monotonically increasing fencing tokens plus checkpoint compare-and-swap prevent expired workers from committing after takeover. Node functions must honor `ctx.signal` for prompt cooperative cancellation.
 

package/docs/working-and-semantic-memory.md

@@ -23,19 +23,44 @@ Ordinary Prism sessions do not require this package or any vector backend.
 | `vectorStore` / `workingStore` | no | Defaults to in-memory adapters |
 | `schema` / `validateWorkingMemory` | no | Working-memory shape checks (JSON Schema subset or host hook) |
 | `workingMemoryTemplate` | no | `{{path}}` template for context injection |
-| `limits` | no | top-K, adjacent range, batch, payload, injected-token caps |
+| `limits` | no | top-K, adjacent range, batch, payload, injected-token, export, and rebuild caps |
 | `redactor` / `secrets` | no | Redact text/metadata before persist/inject |
+| `requireConsent` | no | Strict mode: recall/injection excludes entries lacking explicit consent |
 
-Semantic indexing:
+Semantic indexing (entries carry `MemoryConsent` source/visibility; unset defaults to `{ source: "user", scope: "thread", visible: true }`):
+
+| `MemoryConsent` field | Meaning |
+| --- | --- |
+| `source` | `"user"`, `"agent"`, or `"system"` provenance. |
+| `scope` | `"thread"`, `"profile"`, or `"user"` control scope. |
+| `visible` | `false` immediately excludes the record from recall, injection, export, and telemetry. |
+| `grantedAt` / `revokedAt` | Optional host/audit timestamps; a revocation excludes the record. |
+
+```ts
+await memory.remember({ entries: [{ id, text, metadata?, consent?, sequence? }] }, { wait?: boolean })
+```
+
+Semantic recall (honors consent/visibility at assembly time):
 
 ```ts
-await memory.remember({ entries: [{ id, text, metadata?, sequence? }] }, { wait?: boolean })
+await memory.recall(query, { topK?, messageRange?, requireConsent?, signal? })
 ```
 
-Semantic recall:
+Consent + lifecycle (real grant/correct/delete/retention on stored entries):
 
 ```ts
-await memory.recall(query, { topK?, messageRange?, signal? })
+await memory.setConsent(entryId, { visible?: boolean, source?, scope? }) // grant/revoke; no re-embed
+await memory.correct(entryId, text)                                       // re-embeds, preserves consent
+await memory.forget({ ids? })                                             // real delete (whole thread if no ids)
+await memory.applyRetention({ maxAgeDays?, maxEntries?, batchSize? })     // bounded real-delete sweep
+
+const page = await memory.exportMemory({
+  identity: { tenantId, resourceId, threadId }, // exact host-verified owner
+  cursor?, limit?, maxBytes?, maxMs?, signal?,
+}); // visible, explicitly consented, redacted records only
+
+const rebuilt = await memory.rebuildIndex({ cursor?, batchSize?, maxMs?, signal? });
+// re-embeds one page; save rebuilt.nextCursor and call again to resume
 ```
 
 ## Outputs / response / events
@@ -44,7 +69,12 @@ await memory.recall(query, { topK?, messageRange?, signal? })
 | --- | --- |
 | `updateWorking` / `getWorking` | Versioned `WorkingMemoryRecord` |
 | `remember` | `{ accepted, pending, done }` — default `wait: false` indexes asynchronously |
-| `recall` | `{ hits, adjacent }` tenant/thread scoped |
+| `recall` | `{ hits, adjacent }` tenant/thread scoped; invisible/revoked entries excluded |
+| `setConsent` / `correct` | Updated `MemoryVectorRecord` with stamped grant/revoke times |
+| `forget` | Removed count (real delete) |
+| `applyRetention` | `{ deleted, scanned }` bounded real-delete sweep |
+| `exportMemory` | `{ entries, bytes, nextCursor? }` redacted, explicitly consented, identity-bound page |
+| `rebuildIndex` | `{ rebuilt, nextCursor? }` re-embedded bounded page; caller owns resume scheduling |
 | `createContextProvider()` | Inert `ContextProvider` blocks for working and/or semantic text |
 | `createWorkingMemoryProcessor({ extract })` | Explicit host-invoked updater; never auto-runs |
 
@@ -131,6 +161,8 @@ const memory = createMemory({
 - The working-memory processor is opt-in and host-invoked; middleware is not required.
 - `createHashEmbedder()` is for tests/demos only; production hosts supply a real `Embedder`.
 - Observational memory (`@arnilo/prism-compaction-observational-memory`) remains unchanged and composable.
+- Consent is enforced at the single `recall()` gate, so both direct recall and `createContextProvider()` injection honor it; `visible: false` (or a revoked grant) keeps an entry out of prompts, events, exports, and telemetry. `setConsent`/`correct` re-upsert in place (consent change does not re-embed); `forget`/`applyRetention` are real deletes, not tombstones. Retention uses indexed oldest-first pages plus a scoped count, deleting one default-500/hard-5000 batch without reading a corpus into memory. The PostgreSQL adapter persists consent in a `consent JSONB` column added by `buildMemoryDdl`.
+- `exportMemory()` requires an exact `{ tenantId, resourceId, threadId }` identity equal to its `createMemory()` scope. It excludes legacy consent-less, invisible, and revoked records even when normal recall allows legacy entries. It returns a stable sequence cursor page, redacted before response, with defaults/hard caps of 100/200 entries, 4/32 MiB, and 10/60 seconds. `rebuildIndex()` uses the same stable cursor shape to re-embed one 32/128-record page under a 10/60-second cap; save the cursor durably to resume. Both APIs require a store implementing bounded `listByThread()`; retention also requires `countByThread()`. PostgreSQL/pgvector and the in-memory reference adapter conform; SQLite persistence stores sessions, not semantic vectors.
 - Profile bundles do not include this package yet.
 
 Shared conformance:
@@ -149,10 +181,11 @@ await runMemoryConformance(() => ({
 
 - Every write/query/delete requires `tenantId` + `resourceId`; semantic paths also require `threadId`.
 - Cross-tenant and cross-thread access is denied.
+- Revoked/invisible/non-consented memories never enter prompts, events, exports, or telemetry; `requireConsent: true` additionally drops consent-less (legacy) entries. Consent checks are O(hits) at recall, within the existing injected-token cap.
 - Configure `secrets` / `redactor` so memory text and metadata cannot persist or inject raw canaries.
 - Injected context is inert text — it cannot grant tools or permissions.
 - Hard caps: top-K ≤ 32, messageRange ≤ 4, embed batch ≤ 128, injected tokens ≤ 8000, payload/working-memory byte limits enforced.
-- Every embedding is a non-empty finite number vector. `embedBatched()`, in-memory `VectorStore` upserts/queries, and PostgreSQL/pgvector parameters reject NaN, ±Infinity, non-numbers, and wrong configured dimensions before similarity scoring or SQL. Custom adapters can call `assertFiniteVector(vector, label, expectedLength?)` at their trust boundary.
+- Every embedding is a non-empty finite number vector. `embedBatched()`, in-memory `VectorStore` upserts/queries, PostgreSQL/pgvector parameters, and export/rebuild page boundaries reject NaN, ±Infinity, non-numbers, and wrong configured dimensions before similarity scoring, SQL, response, or re-indexing. Custom adapters can call `assertFiniteVector(vector, label, expectedLength?)` at their trust boundary.
 - Default `remember()` does not block agent completion; pass `{ wait: true }` when indexing must finish first.
 - PostgreSQL live suite is gated by `PRISM_TEST_POSTGRES_URL` and requires the `vector` extension.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",

package/templates/init/providers.json

@@ -72,5 +72,27 @@
     "imports": "import { createAgent } from \"@arnilo/prism\";\nimport {\n  createNeuralWattProvider,\n  defineNeuralWattModel,\n} from \"@arnilo/prism-provider-neuralwatt\";",
     "providerExpression": "createNeuralWattProvider({\n    apiKey: () => process.env.NEURALWATT_API_KEY,\n  })",
     "modelExpression": "defineNeuralWattModel({\n    model: \"glm-5.2\",\n    cache: { kind: \"implicit\" },\n  })"
+  },
+  "alibaba": {
+    "id": "alibaba",
+    "packageName": "@arnilo/prism-provider-alibaba",
+    "envKey": "DASHSCOPE_API_KEY",
+    "envPlaceholder": "sk-...",
+    "modelProvider": "alibaba",
+    "modelName": "qwen-plus",
+    "imports": "import { createAgent } from \"@arnilo/prism\";\nimport {\n  createAlibabaProvider,\n  defineAlibabaModel,\n} from \"@arnilo/prism-provider-alibaba\";",
+    "providerExpression": "createAlibabaProvider({\n    apiKey: () => process.env.DASHSCOPE_API_KEY,\n  })",
+    "modelExpression": "defineAlibabaModel({ model: \"qwen-plus\" })"
+  },
+  "ollama": {
+    "id": "ollama",
+    "packageName": "@arnilo/prism-provider-ollama",
+    "envKey": "OLLAMA_API_KEY",
+    "envPlaceholder": "your-ollama-api-key",
+    "modelProvider": "ollama",
+    "modelName": "gpt-oss:20b",
+    "imports": "import { createAgent } from \"@arnilo/prism\";\nimport {\n  createOllamaProvider,\n  defineOllamaModel,\n} from \"@arnilo/prism-provider-ollama\";",
+    "providerExpression": "createOllamaProvider({\n    apiKey: () => process.env.OLLAMA_API_KEY,\n  })",
+    "modelExpression": "defineOllamaModel({ model: \"gpt-oss:20b\" })"
   }
 }