@xiaozhiclaw/qlogicagent-core 0.6.1 → 0.6.2

package/README.md

@@ -42,9 +42,118 @@ Skill knowledge is maintained by each product with its module version; MCP may
 be its tool execution protocol. The core does not install capabilities.
 
 `getCoreCapabilities()` reports the installed artifact's package version and
-model-callable built-in tool definitions. The current core exposes no built-in
-tools; injected product tools are excluded. Consumers of older artifacts that
-do not export this function must report the inventory as unavailable, not zero.
+supported built-in tool definitions. The development source includes
+`qlogic_ask_user`, `qlogic_discover_capabilities`, `qlogic_search_resources`,
+`qlogic_read_resource`, `qlogic_read_skill`, `qlogic_update_plan` and
+`qlogic_request_confirmation`. Product-injected tools are excluded.
+Older artifacts without this export have an unavailable inventory, not zero.
+Artifact support is distinct from the tools mounted and enabled for a task.
+
+### Host-backed core tools
+
+`createCoreToolAdapter({ host, enabledTools? })` supplies canonical definitions
+and a typed Cloud tool invoker. Only handlers supplied by the Host are enabled;
+an explicit enable list fails if a handler is missing. Nothing is automatically
+added to existing Agent requests. Use `adapter.definitions` in `tools` and
+`availableTools`; keep wire names unique when combining product tools.
+
+```ts
+const core = createCoreToolAdapter({ host: {
+  authorize: (invocation, input, signal) =>
+    product.authorizeCoreRequest(invocation, input, signal),
+  handlers: {
+    qlogic_ask_user: (input, invocation, signal) => product.askUser(input, invocation, signal),
+    qlogic_discover_capabilities: (input, invocation, signal) => product.discoverCapabilities(input, invocation, signal),
+    qlogic_search_resources: (input, invocation, signal) => product.searchResources(input, invocation, signal),
+    qlogic_read_resource: (input, invocation, signal) => product.readResource(input, invocation, signal),
+    qlogic_read_skill: (input, invocation, signal) => product.readSkill(input, invocation, signal),
+    qlogic_update_plan: (input, invocation, signal) => product.updatePlan(input, invocation, signal),
+    qlogic_request_confirmation: (input, invocation, signal) => product.requestConfirmation(input, invocation, signal),
+  },
+} });
+// Supply this invoker to createCloudAgent/createCloudTaskRuntime.
+const toolInvoker = { invoke: (invocation, signal) => core.handles(invocation.name)
+  ? core.invoke(invocation, signal) : product.executeTool(invocation, signal) };
+const tools = [...core.definitions, ...productTools];
+```
+
+Host authorization runs for every validated call with the original trusted
+application/tenant/actor/scope, call ID, round, arguments and task budget.
+Unknown input fields are rejected, including model-supplied authorization claims.
+The Host checks exact resource access and version consistency, supplies its complete
+authorized capability contracts and paginated source evidence, and owns Skill
+enablement/content. Returned `ToolResult` fields are retained without interpretation.
+Resource content is data; no script execution, URL fetching or local file access
+is provided by Core. Unknown Host outcomes are not retried by this adapter.
+
+`qlogic_ask_user` may return a `ToolResult` answer or a `CloudToolWait` of kind
+`input`. Before returning a wait, the Host must persist/deduplicate the question
+against the full original invocation. Configure existing `checkpoints` and
+`onWait` storage; reconcile the user's answer using the existing original receipt
+and `completeCloudToolCheckpoint` or CloudTask `completeWait` path. A clarification
+answer is not permission or confirmation for a business operation.
+
+`CoreToolHandler` distinguishes `CoreToolWait<"qlogic_ask_user">` (`input`)
+from `CoreToolWait<"qlogic_request_confirmation">` (`confirmation`) in both
+public types and runtime validation. In a mixed call batch, a wait suspends the
+task. Calls proven not yet dispatched are durably recorded as `CLOUD_TOOL_DEFERRED`,
+not executed, and can be reconsidered by the Agent after the user's answer.
+Reconciliation preserves these deferrals and existing schema rejection messages.
+Already dispatched calls still require their original confirmed receipts; Core
+does not fabricate success or assume an unknown effect did not occur.
+
+Core argument errors retain a stable `structuredContent.code` and a safe
+`structuredContent.message`, including invalid plan-field locations. Their `error`
+text contains the same diagnostic so a text-only model projection can repair the
+arguments. Products should consume the structured code rather than treating
+the whole human-readable error string as a stable identifier. Authorization errors
+never include private Host exception details.
+
+For resource/search pagination, the Host binds cursors to the authorized query and
+content snapshot, rejecting stale or mismatched cursors. `qlogic_read_skill.version`
+selects the Skill version and supporting resources belonging to that version;
+independently versioned external resources use `qlogic_read_resource` and separate
+authorization. Put essential IDs, revisions and evidence in model-readable `result`
+text or a Host/transport model projection; the full structured receipt remains intact.
+
+`qlogic_update_plan` accepts `CorePlanInput`:
+
+- `create`: `steps` and `issues`, with stable step/issue IDs.
+- `read`: the Host-issued `planId`, including after a worker/process restart.
+- `update`: `planId`, last `expectedRevision`, and the complete replacement
+  `steps` and `issues`. Empty `issues` explicitly clears resolved issues.
+
+Steps contain `description`, `status` (`pending`, `in_progress`, `completed`,
+`blocked`, `cancelled`), optional `dependsOn` step IDs and `evidenceRefs`.
+Issues contain `description` and optional affected `stepIds`. Core rejects
+duplicate IDs, missing dependency/issue references and cyclic dependencies.
+The Host authenticates plan/task ownership, allocates identity, durably saves
+snapshots and atomically compares revisions. Return its plan ID and revision in
+the `ToolResult` (for example `structuredContent`). On revision conflict return
+an error with the current revision; the Agent reads and reconciles before retrying.
+The Host must deduplicate writes by the original invocation; Core neither owns
+a plan database nor retries unknown effects. A progress status or evidence
+reference proposed by the model does not prove business completion.
+
+`qlogic_request_confirmation` accepts `CoreConfirmationInput`: a Host-issued
+immutable `operationRef`, human-readable `summary`, explicit `targets`
+(`resourceId`, optional `version`) and `impacts`. These model fields describe a
+request; they are not authority. The Host must independently resolve the prepared
+operation, validate that the description matches its canonical targets, versions
+and impacts, and display those canonical facts. A changed or unknown operation
+reference must fail rather than create an approval from model claims.
+
+The handler returns an existing authenticated `ToolResult` decision or a wait
+of kind `confirmation`. Persist/deduplicate its request and full invocation before
+waiting, then use the same checkpoints and original receipt recovery as above.
+Approval and rejection are Host-owned results; Core preserves them without
+interpreting them or executing the operation. For CloudTask, the Host's
+`authorizeCompletion` validates the authenticated decision before completion.
+For direct CloudAgent use, validate it before calling `completeCloudToolCheckpoint`.
+The eventual business executor must revalidate the decision against the exact
+prepared operation, actor, scope, resource versions, permission and lifetime.
+Expired, revoked, rejected or changed decisions cannot authorize execution.
+The original-call checkpoint binding does not itself establish approval validity.
 
 Presentation payloads are product-defined id/type envelopes. Core preserves
 their fields without defining choice/table/diagram/attachment schemas or parsing