@arnilo/prism 0.0.12 → 0.0.14

package/docs/work-tools.md

@@ -0,0 +1,117 @@
+# Work tools
+
+Optional `@arnilo/prism-work-tools` package: identity-scoped Microsoft 365 and Google Workspace connectors. Host-pinned CLI binaries only; hard-coded `execFile` argv templates; draft-then-approve mutations; side-effect idempotency; shared mail/calendar/file/task result shapes.
+
+## When to use
+
+Use when agents must read or mutate tenant mail/calendar/files/tasks through the enterprise CLI the host already operates — not through model-built shell strings or generic Graph/Discovery free-form calls.
+
+## Install
+
+```bash
+npm install @arnilo/prism-work-tools
+# host separately:
+#   npm i -g @pnp/cli-microsoft365
+#   npm i -g @googleworkspace/cli
+```
+
+## API
+
+```ts
+import {
+  createWorkTools,
+  createMicrosoft365CliAdapter,
+  createGoogleWorkspaceCliAdapter,
+  createMemoryIdempotencyStore,
+} from "@arnilo/prism-work-tools";
+// or: import { createGoogleWorkspaceCliAdapter } from "@arnilo/prism-work-tools/google-workspace";
+
+const microsoft365 = createMicrosoft365CliAdapter({
+  binary: process.env.M365_BIN!,
+  configDir: `/var/prism/m365/${tenant}/${user}`,
+  identity,
+  // Optional late-bound per-identity token (0.0.14): env var only, never argv/model context.
+  // tokenProvider: createOAuthWorkTokenProvider({ provider: m365OAuth, store, envVar: "M365_ACCESSTOKEN" }),
+});
+
+const googleWorkspace = createGoogleWorkspaceCliAdapter({
+  binary: process.env.GWS_BIN!,
+  configDir: `/var/prism/gws/${tenant}/${user}`,
+  identity,
+  // allowedOps: add docs.create / sheets.create / slides.create when gated
+});
+
+const tools = createWorkTools({
+  microsoft365,
+  googleWorkspace,
+  idempotencyStore: createMemoryIdempotencyStore(),
+  approval: { isApproved: ({ draftId }) => hostHasApproved(draftId) },
+  externalRecipients: { allow: (addr) => addr.endsWith("@contoso.com") },
+});
+```
+
+List/get tools return shared `WorkPage` / `WorkMailMessage` / `WorkCalendarEvent` / `WorkFileItem` / `WorkTaskItem` shapes (`untrusted: true`) via package normalizers — provider-specific fields are not hidden; they are mapped onto the common denominator.
+
+### Hard-coded Microsoft 365 ops
+
+Verified against [CLI for Microsoft 365](https://pnp.github.io/cli-microsoft365/) (2026-07-23):
+
+| Prism op | CLI |
+| --- | --- |
+| `mail.list` | `m365 outlook message list --output json` |
+| `mail.get` | `m365 outlook message get --output json --id …` |
+| `mail.send` | `m365 outlook mail send --output json --to … --subject … --bodyContents …` |
+| `calendar.list` | `m365 outlook event list --output json` |
+| `calendar.add` | `m365 outlook event add --output json --subject … --start … --end …` |
+| `file.list` | `m365 file list --output json --webUrl … --folderUrl …` |
+| `file.add` | `m365 file add --output json --folderUrl … --filePath …` |
+| `file.share` | `m365 spo file sharinglink add` (`--scope organization` only) |
+| `todo.*` / `planner.*` | capability-gated via `allowedOps` |
+
+### Hard-coded Google Workspace ops
+
+Verified against [`@googleworkspace/cli` / `gws`](https://github.com/googleworkspace/cli) (2026-07-24):
+
+| Prism op | CLI |
+| --- | --- |
+| `mail.list` | `gws gmail users messages list --params … --fields …` |
+| `mail.get` | `gws gmail users messages get --params …` |
+| `mail.send` | `gws gmail +send --to … --subject … --body …` |
+| `calendar.list` | `gws calendar events list --params … --fields …` |
+| `calendar.add` | `gws calendar events insert --params … --json …` |
+| `file.list` | `gws drive files list --params … [--page-all]` (NDJSON when paginated) |
+| `file.add` | `gws drive files create --json … --upload …` |
+| `file.share` | `gws drive permissions create` (`type=domain\|user` only; `anyone` denied) |
+| `task.*` | `gws tasks tasks list\|insert\|patch` |
+| `docs.create` / `sheets.create` / `slides.create` | capability-gated via `allowedOps` |
+
+Startup: M365 `version --output json`; GWS `--version`. Forbidden: `login`, `setup`, `auth`, `schema`, `doctor`, `--debug`, `--verbose`, credentials in argv, anonymous share, model-supplied command strings / free-form Discovery.
+
+### Draft → approve → execute
+
+Mutation tools (`*_mail_draft_send`, `*_draft_*`) create an in-adapter draft and return `{ status: "pending_approval", draftId }` until `approval.isApproved` is true. Retries with the same `idempotencyKey` return `{ status: "duplicate" }` after first successful execute.
+
+## Limits
+
+| Resource | Default / hard |
+| --- | ---: |
+| Pagination pages | 20 / 100 |
+| Items / aggregate | 50/500 ; 200/2000 |
+| Body / stdout | 256 KiB–2 MiB / 2–16 MiB |
+| Process wall time | 60 s / 10 min |
+| Concurrent CLI / identity | 2 / 8 |
+
+## Security
+
+- Require host-verified `AgentIdentity`; no cross-identity configDir reuse.
+- Connector tokens (0.0.14): an optional `tokenProvider` resolves a per-identity access token into an env var per call — never argv, never model context. A missing/expired/revoked/cross-identity/wrong-tenant token fails the call closed before any exec. Refresh is late-bound and single-flighted per account (no refresh storm under reconnect). Build one with `createOAuthWorkTokenProvider()` from `@arnilo/prism-credentials-node`.
+- External mail recipients fail closed unless `externalRecipients.allow` returns true.
+- Anonymous / `anyone` sharing denied.
+- CLI stdout/stderr capped; NDJSON page streams strictly parsed and page-capped; process killed on timeout/abort/overflow.
+
+## Related
+
+- [Work connectors](work-connectors.md)
+- [Agent identity](agent-identity.md)
+- [Host security](host-security.md)
+- [Credential storage](credential-storage.md)

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

@@ -25,17 +25,27 @@ Ordinary Prism sessions do not require this package or any vector backend.
 | `workingMemoryTemplate` | no | `{{path}}` template for context injection |
 | `limits` | no | top-K, adjacent range, batch, payload, injected-token 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 consent/source/visibility; unset defaults to `{ source: "user", scope: "thread", visible: true }`):
 
 ```ts
-await memory.remember({ entries: [{ id, text, metadata?, sequence? }] }, { wait?: boolean })
+await memory.remember({ entries: [{ id, text, metadata?, consent?, sequence? }] }, { wait?: boolean })
 ```
 
-Semantic recall:
+Semantic recall (honors consent/visibility at assembly time):
 
 ```ts
-await memory.recall(query, { topK?, messageRange?, signal? })
+await memory.recall(query, { topK?, messageRange?, requireConsent?, signal? })
+```
+
+Consent + lifecycle (real grant/correct/delete/retention on stored entries):
+
+```ts
+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
 ```
 
 ## Outputs / response / events
@@ -44,7 +54,10 @@ 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 |
 | `createContextProvider()` | Inert `ContextProvider` blocks for working and/or semantic text |
 | `createWorkingMemoryProcessor({ extract })` | Explicit host-invoked updater; never auto-runs |
 
@@ -131,6 +144,7 @@ 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 sweeps scan one thread and delete in bounded batches (default 500 / hard 5000) — no full-corpus scan per run. The PostgreSQL adapter persists consent in a `consent JSONB` column added by `buildMemoryDdl`.
 - Profile bundles do not include this package yet.
 
 Shared conformance:
@@ -149,6 +163,7 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -119,6 +119,9 @@
     "packages/server",
     "packages/supervisor",
     "packages/web-tools",
+    "packages/work-tools",
+    "packages/policy",
+    "packages/model-router",
     "packages/browser",
     "packages/ag-ui",
     "packages/prism-*"

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\" })"
   }
 }