@xiaozhiclaw/qlogicagent-core 0.4.0 → 0.5.0

package/README.md

@@ -41,9 +41,10 @@ Context comes from the authenticated product, never from a model/browser claim.
 Skill knowledge is maintained by each product with its module version; MCP may
 be its tool execution protocol. The core does not install capabilities.
 
-Presentation contracts support choices, tables, diagrams, attachments and
-engineering file evidence. Each SaaS renders actual returned content blocks in
-its own UI. Tool names and paths do not imply artifacts or business success.
+Presentation payloads are product-defined id/type envelopes. Core preserves
+their fields without defining choice/table/diagram/attachment schemas or parsing
+engineering files. Each SaaS validates and renders its own returned blocks.
+Tool names and paths do not imply artifacts or business success.
 
 This library has no production dependencies, CLI, desktop host, local tool
 runtime, native session store or per-process credential/policy discovery.
@@ -57,8 +58,18 @@ require request-bound model-service evidence; acknowledged original responses ca
 be replayed without another inference. Sensitive response bodies are excluded from
 progress events. Provider usage is distinct from settlement evidence.
 
-Optional `assistantContext` binds module schema/prerequisites, enterprise configuration
-and source state, employee permissions, and versioned platform Skill/examples.
+Optional `assistantContext` is a product-defined JSON object. Core requires no
+organization, employee, brand, knowledge base or Skill. Only its optional
+`instructions` string supplies trusted product guidance; all other fields are
+factual context and are preserved without interpreting their domain schema.
+Products validate their own fields, examples and references, and supply tools
+and independent verifiers. `tenantId` is an opaque data namespace and may identify
+a personal workspace rather than an organization; `actorId` may identify a user
+or service. Nothing creates an enterprise or membership model in Core.
+The `opaque-v1` context projection is checkpoint-bound. An earlier checkpoint
+with a different context projection requires explicit product migration; Core
+does not reinterpret its saved input or tool receipts. Checkpoints without an
+assistant context retain their existing binding protocol.
 Optional `goal` requires a product `verifyGoal` callback before semantic completion.
 Products may resolve a user-confirmed goal from receipts with `resolveGoal`, and
 return independent verification evidence to the same loop through `goalFeedback`.
@@ -69,6 +80,28 @@ Criteria may carry opaque product `parameters`; verification can return `expecte
 domain rules or declare unsupported criteria satisfied.
 Context anchors carry explicit revision/supersession/source references through
 compaction, keeping unresolved conflicts visible. Product tools retrieve material.
+Optional `runtime.prepareContext(messages, context)` asynchronously retrieves and
+projects product task materials before inference. `context` carries the model,
+input token budget, session/turn IDs and cancellation signal.
+The budget is `Infinity` when context-capacity metadata is explicitly disabled;
+retrieval still runs and the provider remains responsible for its actual capacity.
+Return `{ messages, droppedCount, strategy }`; retrieval and fact updates are applied even
+when `droppedCount` is zero. Keep original intent, current user amendments and
+complete tool call/result groups. Source retrieval, conflicts and summaries remain
+product-owned. Checkpoints retain the projected conversation; original tool receipts
+remain complete. Without this callback, the sliding window retains original intent,
+the latest amendment, current facts and the latest complete protocol group, then
+fills remaining capacity with recent history. These essential messages may exceed
+capacity; Core does not silently drop them or pretend an estimate proves model fit.
+Optional `runtime.countMessageTokens(message, model)` supplies model-aware counts
+for the default window. Its fallback is an advisory serialized-message estimate.
+The input budget reserves configured maximum output tokens rather than a fixed
+percentage; provider context errors remain authoritative.
+After retrieving current product facts, call public
+`prepareSlidingWindowContext(messages, context, countMessageTokens?)` to reuse
+the same canonical window implementation. Product retrieval must not accidentally
+disable context-capacity handling. The helper preserves objective/fact anchors
+and complete tool protocol groups without changing the supplied messages.
 Tool text is complete by default. The removed `maxToolResultChars` option is
 replaced by optional product-owned `runtime.projectToolResult`; persisted receipts
 retain the original result. No quality score controls execution.
@@ -76,6 +109,24 @@ Task request/deadline budgets survive resume; products own atomic financial quot
 reservation through `reserveModelBudget`. Optional delta batching preserves control
 event order and cursor continuity. These contracts do not create new product stores,
 business rules, queues or accounting authorities.
+The task ceiling carries an opaque product ID, accounting unit and positive exact
+decimal string. Core does not round it or impose CNY, four-digit precision or an
+amount range. The injected financial authority must accept or explicitly reject
+that contract and enforce the original ceiling atomically; it remains responsible
+for supported currencies, precision and settlement. The model transport supplies
+normalized usage totals; source names in usage records stay opaque to Core.
+
+Cloud execution does not invent a round limit, per-response tool-call limit,
+retry-count limit, total presentation-block limit, compaction-count stop or default
+tool timeout. Products may supply per-tool `meta.executionTimeoutMs`; task deadlines
+and caller cancellation still propagate to tool execution.
+Omitted round/tool-call limits remain unbounded; explicit `maxToolCalls: 0`
+allows no tool execution, and `maxRounds: 0` means unbounded rounds.
+Products supply their original request, deadline and financial budgets. A retry
+still requires explicit retryability, proven safety and automatic authorization;
+an unknown request is never retried merely because a connection was lost.
+Products retain their own UI schemas and domain validation. Core validates only
+the presentation envelope and keeps all original receipt fields.
 `appendInput(context, taskId, {id, messages, data?})` lets a product append an authenticated
 user amendment to a resolved completed/stopped task. The amendment ID is durable
 and idempotent; a conflicting repeat is rejected. It preserves the original
@@ -94,3 +145,26 @@ task names and error text cannot authorize another paid inference request.
 See the repository's `docs/cloud-runtime.md` for detailed contracts, product
 integration boundaries and acceptance commands. Release status belongs to the
 source workspace README and package registry; this API guide is version-independent.
+
+`createBusinessToolAdapter({port, observe})` adapts a product-owned external job to
+the existing cloud tool wait protocol. `port.submit` deduplicates the original
+invocation; `resolve` calls only `port.query`. Missing/unknown results remain
+external waits, never authorize another submission. Optional `port.cancel`
+returns an authoritative observation rather than assuming cancellation succeeded.
+`observe` persists progress, resource references and outcomes before acknowledgement.
+Forward the immutable `invocation.taskBudget` to paid tools. This adapter owns no
+database, scheduler, polling policy or business condition language.
+
+Optional `agent.shouldPause(context, checkpoint)` reads product-owned durable pause
+intent after a saved `model_ready` checkpoint. It finishes the current model or
+atomic tool receipt first; it does not cancel an unknown effect. The task becomes
+`stopped` with `CLOUD_TASK_PAUSED`. `runtime.resume(context, taskId)` queues that
+same safe checkpoint without new input, resetting no budget, deadline or receipt.
+Products must atomically reopen their dispatch projection for this exact transition.
+
+Original completed-model replay uses the immutable stored messages and digest.
+Current product retrieval is refreshed for subsequent new rounds only. A digest
+mismatch is reconciliation, never permission to pay for a replacement inference.
+An explicit amendment consumes the previous final no-tool response once before
+advancing the round. Reading a saved final response remains possible after the
+original deadline; any new model request or tool effect still observes that deadline.