docs: update planning docs with source decisions
This commit is contained in:
+35
@@ -80,6 +80,41 @@ workspaces/accounts while allowing validation to detect missing, disabled, or
|
||||
incompatible sources.
|
||||
_Avoid_: Ad-hoc environment variables, hidden source lookup
|
||||
|
||||
**Platform Source**:
|
||||
A process-provided source with a fixed identity, such as `wf.std` or
|
||||
`wf.source`. Platform sources can satisfy workflow requirements without
|
||||
deployment self-bindings because their logical source id is also their concrete
|
||||
source id.
|
||||
_Avoid_: Configured account source, user-installed provider
|
||||
|
||||
**Configured Source**:
|
||||
A server/operator-selected source such as an MCP connection, trusted Python
|
||||
module registry, or future OpenAPI provider. Configured sources are where
|
||||
deployment bindings, source registry state, auth refs, catalog cache, and
|
||||
health diagnostics matter most.
|
||||
_Avoid_: Built-in standard library source
|
||||
|
||||
**Source Inventory**:
|
||||
The listable capabilities owned by a source: workflow-callable `NodeSpec`s,
|
||||
provider-native tools, resources, prompts, and related metadata. Inventory
|
||||
inspection is not the same as invoking a tool, reading a resource, or rendering
|
||||
a prompt.
|
||||
_Avoid_: Assuming list equals execute
|
||||
|
||||
**Source Resource Ref**:
|
||||
An inert pass-by-value reference to source-owned content, carrying a logical
|
||||
source and provider URI. The URI is not globally meaningful by itself; runtime
|
||||
must resolve the logical source through deployment/platform context before a
|
||||
helper such as `wf.source.read_resource` can dereference it.
|
||||
_Avoid_: Bare URI, immediate content fetch
|
||||
|
||||
**Prompt Inventory**:
|
||||
Source-owned prompt/template names and metadata. Listing prompts is safe
|
||||
inventory; rendering a prompt is an upstream operation that may be stateful and
|
||||
needs a concrete graph use case, argument schema, and bounded output policy
|
||||
before becoming a workflow helper.
|
||||
_Avoid_: Treating prompt list entries as already-rendered text
|
||||
|
||||
**Workflow Portability**:
|
||||
The goal that a workflow artifact can describe logical requirements separately
|
||||
from concrete source/account bindings. Portability is scoped: deployments bind
|
||||
|
||||
@@ -115,6 +115,12 @@ The runtime does not know whether a node came from MCP, Python, OpenAPI, or a
|
||||
built-in package. It resolves a `NodeSpec`, validates payloads, executes, records
|
||||
trace, and commits reducer-aware state changes.
|
||||
|
||||
Platform sources such as `wf.std` and `wf.source` are process-provided sources.
|
||||
They can appear in artifacts and runs without deployment self-bindings like
|
||||
`wf.std=wf.std`; configured sources such as `local.ops` or `everything.default`
|
||||
still use deployment bindings when a workflow needs portability across accounts
|
||||
or workspaces.
|
||||
|
||||
## Source Model
|
||||
|
||||
The common provider output is `CapabilitySource`.
|
||||
@@ -146,6 +152,17 @@ This seam is for static source inventory. MCP also has runtime pools,
|
||||
auth/catalog stores, admin/apply behavior, and live checks, so it should not be
|
||||
forced into a tiny static interface too early.
|
||||
|
||||
Source inventory is broader than workflow-callable nodes. Sources may own tools,
|
||||
workflow capabilities, resources, and prompts. Current CLI smoke paths can list
|
||||
resource and prompt names with `wf source resources` and `wf source prompts`
|
||||
without fetching resource bodies or rendering prompt templates.
|
||||
|
||||
Resource refs are pass-by-value data using a logical source plus provider URI.
|
||||
`wf.source.read_resource` is the explicit helper that dereferences such refs
|
||||
through runtime/platform context and bounded output policy. Prompt rendering is
|
||||
intentionally not a workflow helper yet; keep it at inventory/inspection level
|
||||
until there is a concrete graph use case and bounded output contract.
|
||||
|
||||
## Demo: Python Source End To End
|
||||
|
||||
Write `ops.py`:
|
||||
@@ -260,10 +277,17 @@ Expected run result:
|
||||
- `wf status` summarizes target, sources, capabilities, runs, admin surfaces,
|
||||
and registry availability.
|
||||
- Capabilities can be listed, inspected, and called directly.
|
||||
- `cap call` has compact/text output options for human and agent smoke checks
|
||||
without dumping large raw provider payloads by default.
|
||||
- Source resource/prompt inventories can be listed safely without reading or
|
||||
rendering upstream content.
|
||||
- Drafts can be created from capabilities and saved as immutable artifacts.
|
||||
- Deployments bind logical sources to concrete sources.
|
||||
- Deployments bind configured logical sources to concrete sources; platform
|
||||
sources such as `wf.std` do not need self-bindings.
|
||||
- Runs are persisted at stopped boundaries and can be inspected/listed.
|
||||
- MCP upstream sessions are stateful through `McpRuntimePool`.
|
||||
- Local/dev auth records support typed OAuth refresh-token credentials and
|
||||
source-owned MCP auth binding; production secret storage remains future work.
|
||||
- Python sources can run through the full draft -> artifact -> deployment -> run
|
||||
lifecycle.
|
||||
|
||||
@@ -278,6 +302,9 @@ Expected run result:
|
||||
- File-backed stores are the proven storage backend; SQL/secret-manager stores
|
||||
are future work.
|
||||
- MCP app/widget passthrough is not a durable workflow product feature yet.
|
||||
- Prompt rendering is not exposed as a workflow helper source yet.
|
||||
- Google Drive MCP is useful as manual OAuth/MCP smoke coverage, but not a
|
||||
reliable regression fixture because provider quotas/permissions are unstable.
|
||||
|
||||
## Next Direction
|
||||
|
||||
|
||||
@@ -123,6 +123,8 @@ The design goals should be stated early and then revisited in evaluation:
|
||||
- validation-centered lifecycle for LLM-authored workflows
|
||||
- typed inputs, state, outputs, and node payloads
|
||||
- explicit source binding
|
||||
- platform sources with fixed process-provided identities, separate from
|
||||
configured workspace/account sources
|
||||
- scoped workflow portability through artifact requirements and deployment
|
||||
binding contracts
|
||||
- durable artifacts, deployments, and stopped runs
|
||||
@@ -250,6 +252,24 @@ The thesis should stress that the runtime does not care where a `NodeSpec` came
|
||||
from. Source-specific behavior belongs in provider packages and server
|
||||
composition.
|
||||
|
||||
Use precise vocabulary:
|
||||
|
||||
- tools are provider-native operations, such as MCP tools
|
||||
- workflow capabilities are `NodeSpec` contracts callable from graphs
|
||||
- resources are source-owned addressable content; a URI is meaningful only with
|
||||
its owning source
|
||||
- prompts are source-owned prompt/template inventory; rendering may be stateful
|
||||
|
||||
Platform sources such as `wf.std` and `wf.source` are process-provided and do
|
||||
not require deployment self-bindings. Configured sources such as MCP, Python,
|
||||
and future OpenAPI sources remain explicit server/operator choices.
|
||||
|
||||
`wf.source.read_resource` is the current explicit dereference helper: workflows
|
||||
pass inert resource refs by value, then the helper resolves the logical source
|
||||
through runtime/platform context and returns bounded text. Prompt rendering is
|
||||
deliberately not a workflow helper yet; keep it in future work unless the thesis
|
||||
adds a concrete graph use case, argument schema, and bounded output policy.
|
||||
|
||||
MCP should be presented as one source family and a useful stress test for
|
||||
source-provider correctness, not as the platform identity.
|
||||
|
||||
@@ -276,6 +296,7 @@ wf config validate
|
||||
-> wf-rpc-server --config
|
||||
-> wf status
|
||||
-> wf source list
|
||||
-> wf source resources / prompts
|
||||
-> wf cap list / inspect / call
|
||||
-> wf draft create-from-capability
|
||||
-> wf draft save
|
||||
@@ -311,6 +332,10 @@ Evaluation should use concrete evidence:
|
||||
- MCP source-provider correctness tests covering tools, resources, prompts, and
|
||||
session reuse through the same server path
|
||||
- Python source workflow-run integration test
|
||||
- bounded source inventory and resource-read tests, especially to avoid raw
|
||||
provider payload spam
|
||||
- OAuth refresh-token/auth-binding tests for HTTP MCP sources, with Google Drive
|
||||
MCP treated as manual smoke coverage rather than a regression fixture
|
||||
- config validation catching import/path errors before server startup
|
||||
- planner-efficiency checks: validation, source catalogs, compact output, and
|
||||
inspectable errors should reduce repeated blind LLM attempts
|
||||
@@ -354,6 +379,10 @@ Possible evaluation questions:
|
||||
- Can the same server be used through CLI and JSON-RPC transport?
|
||||
- Can a new source family be added without changing `wf_core`?
|
||||
- Are large/raw provider payloads bounded in CLI output?
|
||||
- Can platform sources such as `wf.std` be used without self-bindings while
|
||||
configured sources still require explicit bindings?
|
||||
- Can source resources be referenced by logical source and dereferenced only
|
||||
through an explicit bounded helper?
|
||||
- Can an external LLM agent converge on a valid workflow without spending most
|
||||
of the interaction on tool-output spam and trial-and-error?
|
||||
- Does the structured surface reduce failed attempts before success compared to
|
||||
|
||||
Reference in New Issue
Block a user