@collective-intelligence/external-apps-server-sdk 0.1.8 → 0.1.10

package/README.md

@@ -358,6 +358,34 @@ than waiting for a workflow in this bounded tool adapter. The
 shows distinct receipts and final results, independent resource authorization,
 and application-owned execution, recovery, failure, and duplicate protection.
 
+## Workflow results
+
+Workflow invocation returns `runId`. A successful declared-output Workflow run
+read through `runs.get` has `result: { nativeStatus: "completed", output }`;
+the `completed` event from `runs.stream` carries that same object in `data`.
+CI reads the validated, persisted Workflow output snapshot. The Gateway Tool's
+response becomes public only through the Workflow's explicit `outputContract`
+bindings and schema; selecting a Tool alone does not declare a Workflow result.
+See the [binding example and lifecycle](../../../docs/architecture/external-app-gateway.md#workflow-results-and-observation).
+
+The native worker finishes and persists output independently of the browser.
+External terminal publication stays lazy on the next authorized run read, with
+status, result and completion event committed together as an immutable receipt.
+Existing terminal results and cancellation decisions survive repeated reads.
+Owner-user/kind, Organization, Application and external audit-subject checks
+still apply to both snapshots and events.
+
+If reading fails, observe the original `runId` again; do not resubmit the
+business command to retrieve its result. The browser SDK's `runs.follow`
+returns an event page, propagates read failures, and does not retry them
+automatically. Missing promised output is a technical invariant defect, not a
+normal null-output or partial-success terminal result. There is no historical
+terminal-run backfill or compatibility mode for this contract.
+
+Keep analysis history and candidate results in Knowledge reads. Send a matching
+completion notification only after the matching results are actually available
+in Knowledge, even if the command run has already completed.
+
 ## Agent runs and conversations
 
 `agents.invoke({ agentId, input })` starts one Agent run and returns
@@ -517,6 +545,113 @@ const created = await ci.members.createOrGet({
 - Only `temporarily_unavailable` is retryable (the client retries it); a
   creation CI refuses is a non-retryable `internal_error`.
 
+## Durable files
+
+A confidential application stores a file that a workflow run reads later, such
+as the PDF of a signed form. The file is a private stored file of the
+Organization the credentials were authorized for, with no expiry.
+
+```ts
+const uploaded = await ci.files.upload({
+  contentBase64: pdf.toString("base64"),
+  contentType: "application/pdf",
+  fileName: "application.pdf",
+  organizationId,
+  sizeBytes: pdf.byteLength
+})
+// uploaded.value.result: { storageFileId }
+
+await ci.workflows.invoke({
+  input: { document: { storageFileId: uploaded.value.result.storageFileId } },
+  organizationId,
+  workflowFqn
+})
+```
+
+- `contentType` is `application/pdf`, `image/jpeg` or `image/png`, and the file
+  holds 1 byte to 10 MiB. `sizeBytes` must match the decoded content. Other
+  files are refused with `invalid_request`.
+- A workflow input can name the `storageFileId`; the nodes of a run of the same
+  Organization read the file through their stored file access. The file has no
+  public URL, and another Organization cannot read it.
+- `attachments.upload` is different: its file belongs to one run and expires
+  after 24 hours.
+- It needs the `ai:attachments` scope. Only service credentials may call it: a
+  delegated user token or an anonymous visitor gets `operation_not_allowed`.
+
+### Entity File fields
+
+A File field of an entity schema takes a different flow: the file becomes a
+File value of the entity, not a stored file a workflow reads.
+`resources.createUpload` asks CI for a single-use upload slot, the server PUTs
+the bytes straight to storage, and the entity write through CI's resources API
+names the slot's `uploadId` as `{ upload }` for that File field key:
+
+```ts
+const slot = await ci.resources.createUpload({
+  field: "memberLogo",
+  filename: "logo.png",
+  mimeType: "image/png",
+  organizationId,
+  schemaId: "apito.vetrina.schemas.member-company"
+})
+if (slot.ok) {
+  const { headers, method, uploadId, url } = slot.value.result
+  await fetch(url, { body: logo, headers, method })
+  // The entity write then sends { memberLogo: { upload: uploadId } }.
+}
+```
+
+- Two credentials can ask for a slot, as for entity writes: the member's
+  delegated token (`exchangeMemberSession`), writing as that member; or the
+  application's service credential, for schemas declared by the application's
+  own package only, writing as the Organization default service principal.
+  `schemaId` is the schema id or FQN.
+- A refusal resolves `{ ok: false, error }` with CI's `correlationId` and a
+  `code`; `upload_not_supported` means the Organization storage cannot presign
+  uploads. Only `retryable` failures are retried.
+- Each attempt, request and response body, is bounded by `timeoutMs`
+  (10 seconds by default); a CI that stops answering ends in a retryable
+  `unavailable`. `signal` cancels: a cancelled request rejects with the
+  signal's reason.
+- The PUT is the caller's: send exactly `headers` to `url` with `method`. No
+  file bytes pass through CI's API. A slot is single use: the first successful
+  write consumes it; request a new one to retry.
+- The write form of a File field key is `{ upload }` to add the uploaded file,
+  `{ id }` (or a File value read before) to keep a file, an ordered array for a
+  multiple field, or `null` to remove every file. Omit the key to keep its
+  files.
+- `/runtime/effect` exports the Effect schemas `EntityFileValue` (a File value
+  as CI reads return it), `EntityFileWrite` (one file of a write) and
+  `EntityFileFieldWrite` (the write form of a File field key). Their types
+  equal the client SDK types of the same name. They validate CI entity
+  values; a portable resource form has no File field, so
+  `projectResourceSchema` refuses them.
+
+## Runtime origin
+
+The browser origins of an Organization are the `allowedOrigins` that its
+installed applications declare, plus one runtime origin per application. A
+confidential application sets its runtime origin, for example the URL of each
+new deployment; CI keeps storage CORS in line with the Organization origins, so
+a browser on that origin can upload to a presigned storage URL.
+
+```ts
+await ci.origins.setRuntime({
+  organizationId,
+  origin: `https://${process.env.VERCEL_URL}`
+})
+// value.result: { origin }
+```
+
+- Each call replaces the application's previous runtime origin, so the list
+  does not grow; declare stable origins, such as the production site, in
+  `allowedOrigins`.
+- `origin` is an exact HTTPS origin (`https://host[:port]`, no path), or a
+  loopback HTTP origin with a port; other values get `invalid_request`.
+- It needs the `origins:write` scope. Only service credentials may call it: a
+  delegated user token or an anonymous visitor gets `operation_not_allowed`.
+
 ## Member company links
 
 An application links a member of its Organization to the Knowledge company
@@ -1407,6 +1542,21 @@ The adapter never retries or follows redirects. Cancellation or a lost response
 after dispatch remains an uncertain outcome; retain the original action for
 explicit resubmission.
 
+#### File uploads through the BFF
+
+When the definition declares `capabilities.upload: true`, the handler also
+accepts `POST {basePath}/uploads` with `{ field, filename, mimeType }`. It calls
+`authorize` with the operation `upload`, then forwards the request with the
+verified grant to `/application/v1/resources/{schemaFqn}/uploads`. CI answers
+the File upload `{ uploadId, url, method: "PUT", headers }`; the browser PUTs
+the bytes straight to that storage URL, so no file bytes pass through the BFF.
+The entity write that names `{ upload: uploadId }` follows the normal update
+path. `upload_not_supported` (the Organization storage can not presign) maps to
+HTTP 400. Without the capability the request answers `capability_not_supported`
+and is not forwarded. A local `defineEntityResource` binding answers
+`capability_not_supported`, and a `defineCrudResource` handler answers 404 for
+this path. The client SDK README documents the write form.
+
 ## Optional local user authentication
 
 Import `createBetterAuth` only from