@mitralab.io/sdk-core 0.1.1 → 0.2.0-beta.1

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 All notable changes to this project are documented in this file.
 
+## 0.2.0-beta.1
+
+This working tree prepares the `0.2.0-beta.1` package. Publication provenance remains
+unreleased until the final source commit and registry artifact exist.
+
+- Accept an inline template definition on integration config creation and on
+  provisional credential tests, so an app can connect a provider that has no
+  catalog template. `fieldsSchemaInline`, `requestConfigInline`, and
+  `loginConfigInline` replace `templateId` and reuse the catalog shapes. The
+  producer owns the exclusivity between the two, and Core does not check it.
+- Add `IntegrationFieldSchemaInput`, the authoring shape for an inline field,
+  which leaves `placeholder` and `default` optional because the producer stores
+  an omitted one as null. Responses keep the strict `IntegrationFieldSchema`.
+- Read `templateId: null` on configs created from an inline definition and
+  validate the three inline fields echoed back on config and list responses.
+- Publish contract corpus `0.2.0-beta.1` with the inline create, credential
+  test, and listing cases, leaving the released `0.2.0-beta.0` bytes untouched.
+- Name the array in the integration template field-schema validation message.
+  It now reads `fieldsSchema field 0` instead of `field 0`, because the template
+  and inline paths share one validator. Consumers that reimplement Core response
+  validation, such as the Python SDK, follow the same wording.
+
+## 0.2.0-beta.0
+
+This working tree prepares the `0.2.0-beta.0` package. Publication provenance remains
+unreleased until the final source commit and registry artifact exist.
+
+- Map all 120 tools exposed by the MCP alpha catalog to direct, split, alias, or
+  composition-based typed Core capabilities in a versioned parity artifact.
+- Add Code Studio app, file, build, deploy, version, and rollback operations.
+- Include the producer-supported app icon in create inputs and document Code
+  Studio deploy and version pagination defaults.
+- Add schema, custom query, import, full Data Source, Function administration,
+  agent, workflow, integration resource/template, Copilot, Messenger, member,
+  and app context operations.
+- Add synchronous and asynchronous anonymous public Function execution through
+  a dedicated optional transport with no authenticated-transport fallback.
+- Add structural page and nullable response helpers while preserving the
+  dependency-free injected transport architecture.
+- Preserve producer `createdAt: null` values in `FunctionExecution`,
+  `FunctionDefinition`, and Custom Query summary and definition responses.
+- Preserve producer `createdAt: null` values in `AgentTask` responses, which the
+  Copilot rename mutation returns without the field.
+- Preserve full Function batch replacement over PUT while mapping the MCP
+  `bulkUpdateFunctions` patch semantics to a separate PATCH operation.
+- Add embedded cron fields to single-Function create and patch inputs and
+  validate those fields in detail and list responses. Dedicated bulk input
+  types exclude the schedule fields discarded by the producer's bulk paths.
+- Keep scheduling on the composed Function contract and omit the duplicate
+  schedule lifecycle facade and single-Function full-replacement PUT.
+- Map MCP Function execution lookup to the nested administration route that
+  requires both Function and execution identifiers.
+- Separate producer summary and detail DTOs for apps, integration templates,
+  template configs, and integration resources, and validate their complete
+  response shapes together with app versions and Workflow executions.
+- Apply newest-first Code Studio deploy and version sorting by default while
+  preserving an explicit caller sort.
+- Execute integration template configs by app-scoped alias with the same proxy
+  request and response contract used for config identifiers.
+- Keep resource execution on `integration.executeResource()` and omit the
+  duplicate authoring-module method. Document `integrationAdmin.list()` as the
+  direct app-scoped integration listing contract.
+- Forward optional Virtual Table and connection settings when creating Custom
+  Queries.
+- Forward each Agent session's transport preference to the concrete event
+  source without coupling Core to HTTP or WebSocket.
+- Match stable producer pagination while preserving Integration's legacy flat
+  page shape, and return the complete Data Manager records envelope.
+- Align IAM current-user, Data Source, Import, Integration connection, Custom
+  Query execution, and Messenger notification DTOs with their alpha producers.
+- Build app context only from capabilities authorized to an app-scoped token;
+  member access remains an explicit IAM operation requiring `MEMBER_READ`.
+
 ## 0.1.0
 
 - Add environment-neutral transport and error interfaces.

package/README.md

@@ -7,7 +7,9 @@ Most application and Server Function code should install a concrete SDK instead:
 - `@mitralab.io/platform-sdk` for browser applications
 - `@mitralab.io/functions-sdk` for Mitra Server Functions
 
-The core package exists so both SDKs build entity, custom query, Function, integration, and current-user requests from one contract.
+The core package exists so concrete SDKs build direct backend requests from one
+contract. It exposes the API values returned by each service. It does not expose
+MCP envelopes, `CallToolResult`, or MCP-formatted text.
 
 The versioned contract corpus in `contracts/` is the canonical source for the
 MCP, JavaScript, and Python capability matrix. Its manifest identifies the
@@ -23,7 +25,17 @@ The package contains:
 - common types and data transfer objects
 - safe path segment encoding
 - structural response validation
-- `auth.me`, entities, queries, Functions, and integration modules
+- authentication and app members
+- Code Studio apps, files, builds, deploys, versions, and rollback
+- schema, records, custom queries, SQL, imports, and Data Sources
+- Functions, versions, publishing, rollback, executions, visibility, and secrets
+- Function scheduling composed into single-Function create, patch, get, and list
+- business agents and workflows
+- integration configs, resources, templates, tests, proxying, and executions
+- Copilot tasks, messages, credentials, models, and app connections
+- a transport-agnostic Agent task live-session state machine with bounded queue and `sendAndWait`
+- Messenger notifications and composed safe app context
+- anonymous public Function execution
 - a minimal transport interface injected by each concrete SDK
 
 The package does not contain:
@@ -35,6 +47,36 @@ The package does not contain:
 
 Those concerns stay in the concrete SDK because browser sessions and Server Function runtime credentials have different security and failure semantics.
 
+## Agent task live sessions
+
+Core owns the state machine but never opens a network connection. A concrete SDK implements
+`AgentTaskEventSource`, then composes it with the REST task module:
+
+```typescript
+import {
+  createAgentTaskSessionManager,
+  withAgentTaskSessions,
+  type AgentTaskEventSource,
+  type SdkCore,
+} from "@mitralab.io/sdk-core"
+
+declare const eventSource: AgentTaskEventSource
+declare const core: SdkCore
+
+const sessions = createAgentTaskSessionManager({ tasks: core.agentTasks, eventSource })
+const agentTasks = withAgentTaskSessions(core.agentTasks, sessions)
+const session = agentTasks.session({ taskId: "task-id", transport: "http" })
+const result = await session.sendAndWait("Summarize the app", { timeoutMs: 120_000 })
+```
+
+The event source must complete `open()` after its streaming handshake, so Core opens the channel
+before posting the prompt. Core forwards the session's `auto`, `websocket`, or `http` transport
+preference to `open()`; the concrete adapter selects or rejects it. HTTP/SSE has no replay cursor.
+During an active turn Core performs one
+reconnection and reconciles persisted messages; live deltas across that gap are not guaranteed to
+be lossless. Abort and timeout stop the local `sendAndWait` waiter but do not interrupt the remote
+turn. Use `cancel()` when interruption is intended.
+
 ## Installation
 
 ```bash
@@ -54,28 +96,197 @@ declare const iam: Transport
 declare const dataManager: Transport
 declare const functions: Transport
 declare const integration: Transport
+declare const codeStudio: Transport
+declare const copilot: Transport
+declare const messenger: Transport
+declare const publicFunctions: Transport
 
-let dataSourceId: string | undefined
+let appId: string | undefined
 
 const core = createSdkCore({
-  transports: { auth: iam, dataManager, functions, integration },
-  getDataSourceId: () => dataSourceId,
+  transports: {
+    auth: iam,
+    dataManager,
+    functions,
+    integration,
+    codeStudio,
+    copilot,
+    messenger,
+    publicFunctions,
+  },
+  getAppId: () => appId,
   functions: {
     executeInvocationType: "sync",
     emptyInput: "empty-object",
   },
 })
 
-const tasks = await core.entities.getTable("Task").list({ limit: 20 })
+const { data: tasks } = await core.entities.getTable("Task").list({ limit: 20 })
+const context = await core.context.getAppContext()
 ```
 
 The transport owns URL resolution, authentication, serialization, error parsing, redirects, retries, and timeouts. The core never reads or stores credentials.
 
-Custom query requests currently target the Data Manager `main` contract and
-send both `dataSourceId` and `parameters`. The recorded `alpha` contract accepts
-that body but ignores `dataSourceId`, resolving the data source from the
-authenticated app instead. The SDK does not retry this POST with another body
-because the first request can already execute.
+List methods return the producer's summary DTO when it differs from the detail
+response. Custom Query summaries omit `sql`, Workflow summaries omit
+`definition`, and integration resource summaries contain only `id`, `name`,
+`method`, and `endpoint`. App, integration template, and template config lists
+likewise expose their producer summary DTOs, while their `get` methods return
+the complete detail DTOs.
+
+Record list and filter methods preserve the Data Manager envelope with `data`,
+`limit`, `skip`, `total`, and `hasMore`. Spring list endpoints from Code Studio,
+Functions, Data Manager, and Copilot use stable pagination metadata under
+`page`. Integration still returns its legacy flat Spring page metadata, so its
+list methods expose `totalElements` at the top level.
+
+The complete DTOs preserve producer field names and nullability. This includes
+Code Studio app routing, domains, color, plan, version, and timestamps;
+Workflow execution scope, trigger, current step, context, and timestamps; and
+Integration template login/request schemas, config metadata, and resource
+parameter schemas. `apps.build()` returns the `AppDeploy` produced by the build
+endpoint. `apps.publish()` continues to return the updated `AppDefinition`.
+
+Code Studio deploys use the producer field names `deployUrl` and
+`errorMessage`, together with `appId`, `appVersionId`, `logs`, `durationMs`,
+`startedAt`, `finishedAt`, and `createdAt`. Integration execution history uses
+`success` rather than a synthetic status and preserves nullable request,
+response, error, source, and duration fields.
+
+Integration configs can be executed by identifier with `integration.execute()`
+or by their app-scoped alias with `integration.executeByAlias()`. Both methods
+send the proxy request unchanged apart from the required `source: "SDK"` audit
+field and validate the same proxy result.
+
+An integration config normally points at a catalog template through `templateId`.
+When the provider has no template, `integrationAdmin.create()`,
+`integrationAdmin.bulkCreate()`, and `integrationAdmin.testCredentials()` accept
+an inline definition instead, in the same shapes the catalog uses:
+
+```typescript
+await integrationAdmin.create({
+  alias: "erp-inline",
+  fieldsSchemaInline: [
+    { key: "base_url", label: "Base URL", type: "url", required: true },
+    { key: "access_key_code", label: "Access Key Code", type: "secret", required: true },
+    { key: "access_key_token", label: "Access Key Token", type: "secret", required: true },
+  ],
+  requestConfigInline: {
+    headers: {
+      "X-Access-Key-Code": "{{access_key_code}}",
+      "X-Access-Key-Token": "{{access_key_token}}",
+    },
+    credential_rules: null,
+  },
+  loginConfigInline: null,
+  values: { base_url: "https://api.example.com", access_key_code: "...", access_key_token: "..." },
+})
+```
+
+Send `templateId` or the inline definition, never both and never neither. The
+Integration service owns that rule and answers 400; Core forwards whatever the
+caller sends. Configs created this way report `templateId: null` and echo the
+three inline fields back on every config response, with secrets in `config`
+masked exactly as they are for template-backed configs.
+
+Inline fields are authored as `IntegrationFieldSchemaInput`, which makes
+`placeholder` and `default` optional because the producer stores an omitted one
+as null. Responses keep the strict `IntegrationFieldSchema`, where both
+properties are always present.
+
+`integrationAdmin.list()` is the native equivalent for listing configured
+integrations. It calls `GET /api/v1/template-configs` and returns the producer's
+paginated `TemplateConfigSummary` values. With an app-scoped token, the
+Integration service filters the page to that app.
+
+`auth`, `dataManager`, `functions`, and `integration` remain required for
+backward compatibility. `codeStudio`, `copilot`, and `messenger` are optional;
+calling their modules without the corresponding transport fails with a
+configuration error before making a request.
+
+`publicFunctions` is deliberately separate and never falls back to the
+authenticated Functions transport. Its adapter must target the Functions public
+base URL and must not attach `Authorization` or `X-App-Id`. It calls
+`POST /public/v1/functions/{id}/execute` with `X-Invocation-Type: sync` or
+`async`. Public async is fire-and-forget because the producer does not expose
+anonymous polling. Callers that need a result use public sync execution, or the
+authenticated `functions.executeAsync` and `functions.getExecution` methods.
+
+## App scope and permissions
+
+Core accepts app identifiers but does not inspect tokens or implement service
+authorization. A concrete app-scoped adapter must fix `appId` to its trusted
+runtime value. It must not let caller input select another app. This is
+especially important for Code Studio because its alpha endpoints do not enforce
+an app claim in every path. `apps.list()` and `apps.create()` are tenant-wide and
+are not available to app-scoped tokens.
+
+`context.getAppContext()` always uses the trusted current app and deliberately
+excludes app members. The Server Function token does not have `MEMBER_READ`, so
+the composed context must not call IAM's member endpoint. `members` remains a
+separate Core module for callers whose token has that permission. Function
+secret operations still require their dedicated permissions. Agent tools that
+resolve a business `agent_id` and the two tenant-wide app collection operations
+are not applicable to an app-scoped token. Messenger delivery also depends on
+a configured channel. These are service authorization constraints, not changes
+to the remaining Core contracts.
+
+Custom Query creation accepts optional `isVirtualTable` and `connectionId`
+fields and forwards them unchanged to the Data Manager. Omitting
+`isVirtualTable` preserves the producer default of `false`; `connectionId` only
+selects an external connection for a Virtual Table.
+
+Custom query execution targets the Data Manager alpha contract and sends only
+`parameters`. Data Manager resolves the Data Source from the authenticated app,
+so the concrete adapter must use the app-scoped JWT and must not accept a caller
+selected Data Source for this operation.
+
+## MCP capability coverage
+
+[`contracts/v0.2.0-beta.0/mcp-tool-parity.json`](contracts/v0.2.0-beta.0/mcp-tool-parity.json)
+maps all 120 `@McpTool` methods from 18 alpha tool classes to the typed Core
+surface. Multiplexed MCP tools map to separate SDK methods. Composition and alias
+tools record equivalence instead of creating duplicate APIs. Git credentials are
+excluded because they are an internal Sandbox endpoint, not an MCP capability.
+The deprecated Functions bridge remains owned by `@mitralab.io/functions-sdk`.
+
+The MCP `bulkUpdateFunctions` tool maps to `functionsAdmin.bulkPatch()` and
+`PATCH /api/v1/functions/bulk`, preserving omitted fields. The separate
+`functionsAdmin.bulkUpdate()` method remains a full replacement over PUT.
+Single-Function create and patch inputs also expose `cronExpression`,
+`cronInputJson`, and `cronEnabled` as one composed scheduling unit. On create,
+omitting all three creates no schedule; supplying any of them requires a
+non-blank `cronExpression`. The new schedule uses `UTC` and starts `ACTIVE`
+unless `cronEnabled` is `false`. On patch, null or omitted schedule fields
+preserve their stored values, an empty `cronInputJson` object clears the input,
+and a blank `cronExpression` removes the schedule. A non-blank expression can
+create a missing schedule in `UTC`; `cronEnabled` explicitly pauses or resumes
+it. These composed writes require `SCHEDULE_WRITE` and `FUNCTION_EXECUTE` in
+addition to the Function write permission.
+
+Function detail and list responses return all three fields when the caller has
+`SCHEDULE_READ`. Without it, all three are null without querying Scheduler. The
+same all-null shape represents a Function that has no schedule, so these
+responses alone cannot distinguish absence from missing read permission. All
+Function bulk create, update, and patch inputs prohibit embedded schedule
+fields; their dedicated types omit them. Compose scheduling only through the
+single-Function create and patch methods.
+
+The MCP `FunctionTools.getExecution` operation maps to
+`functionsAdmin.getExecution(functionId, executionId)` and its nested Function
+execution route. The runtime-only `functions.getExecution(executionId)` remains
+available for callers of the separate global execution endpoint.
+
+Core deliberately exposes no separate schedule facade. The MCP scheduling capability is composed
+through the three cron fields on `functionsAdmin.create()` and `patch()`, with state returned by
+`get()` and `list()`. This keeps one public Function contract instead of duplicating the Scheduler
+producer lifecycle.
+
+Legacy Git credentials and record operations selected by `jdbcConnectionConfigId` have no native
+Core equivalent. Git credential minting is an internal Sandbox operation authenticated between
+services, and the public Data Manager records API resolves the app Data Source from the token
+without accepting a connection selector. Core does not synthesize either behavior through a BFF
+or raw SQL.
 
 ## Error mapping
 
@@ -89,3 +300,23 @@ npm run check
 ```
 
 The build produces ESM, CommonJS, `.d.ts`, and `.d.cts` artifacts. Package smoke tests install the generated tarball into a clean consumer and validate both module systems and TypeScript resolution.
+
+## Release order
+
+Core is the producer for the concrete SDK adapters, so it publishes first. For a prerelease
+`X.Y.Z-beta.N`, currently `0.2.0-beta.1`:
+
+1. Merge the source, the `package.json` version, and the matching contract corpus version to
+   `main` in the same pull request. The Release workflow bumps nothing.
+2. Run the Release workflow with version `X.Y.Z-beta.N`. It checks that the requested version
+   already matches `package.json`, runs the full package check, then tags and publishes the
+   prerelease under npm's `beta` dist-tag.
+3. Confirm `npm view @mitralab.io/sdk-core@X.Y.Z-beta.N version` returns the same version.
+4. Regenerate each adapter lockfile from the npm registry and pin this repository commit in the
+   adapter's contract-source manifest before publishing that adapter.
+
+Stable `X.Y.Z` releases use npm's default `latest` dist-tag. The workflow accepts only that stable
+form or the prerelease form `X.Y.Z-beta.N`.
+
+Do not publish an adapter against a local tarball or a `file:` dependency. Tarballs are only for
+pre-release validation while the registry artifact does not exist.

package/contracts/README.md

@@ -10,22 +10,67 @@ change requires a new version directory. Consumers may vendor the exact bytes
 and pin their copy with a SHA-256 digest so their tests never depend on network
 access.
 
+A released version directory is immutable. Adding an operation, or widening the
+request or response of one that already exists, means publishing a new version
+and moving `current`, never editing bytes another consumer already pinned. Every
+declared version keeps its digest verified, so a consumer that has not migrated
+stays on the version it vendored.
+
+The `current` version names the package release that will publish it, so it moves
+together with `package.json` in the pull request that prepares that release. The
+release workflow does not bump anything: it checks that the requested version
+already matches `package.json`, runs the full package check, then tags and
+publishes.
+
+## Versions
+
+- `0.1.0` covers the runtime surface: current user, entities, custom queries,
+  Function execution, and integration proxying.
+- `0.2.0-beta.0` adds the builder tier: SQL batches and table listing, Data Source
+  batches, Function administration batches, integration template config
+  batches with connection tests and listing, and app members. Its `sources`
+  entries pin the producer revisions currently on `origin/alpha`.
+- `0.2.0-beta.1` widens integration template configs with the inline definition
+  contract. A create item or credential test carries `fieldsSchemaInline`,
+  `requestConfigInline`, and `loginConfigInline` instead of a `templateId`, and
+  config responses report `templateId: null`. Operations that accept more than
+  one request shape now keep one success case per shape. It declares no MCP
+  companion artifact because the MCP tool surface is unchanged and each artifact
+  carries its own version identity; the matrix stays pinned at `0.2.0-beta.0`.
+  The `integrationBuilder` source pin still names the last revision on
+  `origin/alpha`, because the producer change is landing in mitra-integration#37.
+
+The `0.2.0-beta.0/mcp-tool-parity.json` companion artifact maps every one of the 120
+`@McpTool` methods on `mitra-mcp-server` `origin/alpha` to a typed Core method.
+It labels multiplexed tools as split methods and composition or alias tools as
+equivalences, so coverage does not require artificial duplicate APIs. The
+manifest pins the companion artifact independently.
+
+`0.2.0-beta.0/mcp-alpha-tools.json` is the offline source snapshot behind that matrix.
+It records the MCP source paths, class names, complete method signatures, alpha
+commit, and a digest over canonical lines containing each return type, method
+name, and named parameter type. This makes request and response signature drift
+fail the contract check even when a tool keeps the same name. Refresh and verify
+it against a fetched MCP checkout with:
+
+```bash
+npm run snapshot:mcp -- ../mitra-mcp-server origin/alpha
+```
+
 Core executes one success case for every operation plus Core-owned response
 validation cases. Functions JavaScript inherits those checks from Core and must
 consume every HTTP adapter case itself. Python does not depend on Core, so it
 must consume every success, response-validation, and HTTP adapter case. The
 consumer requirements in the fixture make those obligations machine-readable.
 
-## Custom query transition
-
-The `customQueryTransition` section intentionally models two different server
-contracts:
+The executable Function batch cases keep two different contracts: full
+replacement through `bulkUpdate` and PUT, and partial preservation through
+`bulkPatch` and PATCH. The MCP `bulkUpdateFunctions` tool maps only to the latter.
 
-- Data Manager `main` consumes `dataSourceId` and `parameters`.
-- Data Manager `alpha` accepts that same body, ignores `dataSourceId` during
-  deserialization, and resolves the data source from the authenticated app.
+## Custom query execution
 
-The current SDK release still targets `main`, but its body is transport-compatible
-with the recorded `alpha` contract. The semantics differ because alpha ignores
-the supplied identifier. Do not add an automatic POST fallback because the first
-request can already execute and a retry could execute the query twice.
+The `customQueryExecution` section records the Data Manager `origin/alpha`
+contract used by this beta. The request body contains only `parameters`, and the
+producer resolves the Data Source from the authenticated app. Concrete adapters
+therefore supply the app-scoped JWT instead of accepting a caller-selected Data
+Source identifier.

package/contracts/manifest.json

@@ -1,11 +1,25 @@
 {
   "contract": "SDK-PARITY-001",
-  "current": "0.1.0",
+  "current": "0.2.0-beta.1",
   "versions": [
     {
       "version": "0.1.0",
       "path": "v0.1.0/sdk-parity.json",
       "sha256": "600be3688cea7cfef16a8cf347516e87949b8e4151efb2c4136a2345557dde70"
+    },
+    {
+      "version": "0.2.0-beta.0",
+      "path": "v0.2.0-beta.0/sdk-parity.json",
+      "sha256": "0f41764eedce0945b0b696b6f95af4d76c31a63df169b088b8a6f65d0aa841d4",
+      "mcpToolsPath": "v0.2.0-beta.0/mcp-tool-parity.json",
+      "mcpToolsSha256": "77a115d39e2ee195b4e33a86766a6fdd75e89a7a35b6102f6f38f0eeb8c9d587",
+      "mcpSourcePath": "v0.2.0-beta.0/mcp-alpha-tools.json",
+      "mcpSourceSha256": "480d27eed75f2604da07fadd10f236a0ca971cf6a3c003434a1fb62c4255178f"
+    },
+    {
+      "version": "0.2.0-beta.1",
+      "path": "v0.2.0-beta.1/sdk-parity.json",
+      "sha256": "eb9515241cd092727ddb8cde3e3062df041a4c91f8226da04dc987b7c1053f05"
     }
   ]
 }