bccc39f741
Propagates `taskEnv` (task-scoped environment variables) through the agent session creation pipeline, including executor sessions, spawned child agents, and workflow sessions. The engine's session factory (`agent-session-helpers.ts`), executor, PI agent creation (`pi.ts`), and step session executor Fusion-Task-Id: FN-3961
73 lines
4.0 KiB
Markdown
73 lines
4.0 KiB
Markdown
# fusion-plugin-cli-printing-press
|
|
|
|
Bundled first-party Fusion plugin for generating and managing service CLIs.
|
|
|
|
## Storage & Config Model
|
|
|
|
### Tables
|
|
|
|
- `cli_press_services`: service metadata (`id`, `slug`, `displayName`, `description`, `baseUrl`, `sourceKind`, `sourceRef`, timestamps)
|
|
- `cli_press_cli_specs`: generated/spec inputs per service (`id`, `serviceId`, `name`, `version`, `generatorVersion`, `specJson`, `generatedAt`, `status`, `lastGenerationError`, timestamps)
|
|
- `cli_press_artifacts`: generated artifact metadata (`id`, `cliSpecId`, `kind`, `path`, `executable`, `checksum`, `sizeBytes`, timestamps)
|
|
- `cli_press_credentials`: non-OAuth credentials (`id`, `serviceId`, `name`, `kind`, `value` envelope, `placement`, timestamps)
|
|
- `cli_press_service_settings`: service-scoped key/value settings (`id`, `serviceId`, `key`, `value`, `scope`, timestamps)
|
|
|
|
All IDs are UUIDv4-based with prefixes: `svc_`, `cli_`, `art_`, `cred_`, `set_`. Timestamps are ISO-8601 strings.
|
|
|
|
### Exported Types
|
|
|
|
- `Service`: canonical external-service record
|
|
- `CliSpec`: persisted cli-printing-press spec/generation state
|
|
- `CliArtifact`: artifact file metadata (path stored relative to `<projectRoot>/.fusion/`)
|
|
- `Credential`: persisted secret envelope + placement metadata
|
|
- `CredentialKind`: closed union of non-OAuth kinds (`api_key`, `bearer_token`, `basic_auth`, `header`, `query_param`, `env_var`)
|
|
- `CredentialPlacement`: discriminated placement union
|
|
- `ServiceSetting`: service-level setting entry (`runtime` | `wizard` | `metadata`)
|
|
- `OAuthNotSupportedError`: thrown when oauth/oauth2 is passed
|
|
- `InvalidCredentialPlacementError`: thrown on kind/placement mismatch or invalid `api_key` placement
|
|
|
|
### Credential placement union
|
|
|
|
- `{ kind: "header", header: string }`
|
|
- `{ kind: "query_param", queryParam: string }`
|
|
- `{ kind: "env_var", envVar: string }`
|
|
- `{ kind: "bearer_token", header: string }`
|
|
- `{ kind: "api_key", header?: string, queryParam?: string }` (exactly one required)
|
|
- `{ kind: "basic_auth", header: string }`
|
|
|
|
### Credential encoding/materialization
|
|
|
|
- Values are stored as `{ encoding: "base64", value: string }` via `encodeCredentialValue`/`decodeCredentialValue`.
|
|
- `applyCredentialToRequest` materializes credentials into `{ headers, query, env }` and rejects OAuth at runtime.
|
|
|
|
### OAuth policy (deferred)
|
|
|
|
OAuth/OAuth2 flows are intentionally excluded from v1. Any `oauth`/`oauth2` kind is rejected by store-layer and helper-layer guards with `OAuthNotSupportedError`. Follow-up remains tracked in **FN-3762**.
|
|
|
|
### Artifact path convention
|
|
|
|
Generated artifacts are expected under:
|
|
`<projectRoot>/.fusion/plugins/cli-printing-press/artifacts/<serviceId>/<specId>/<artifactFile>`
|
|
|
|
`CliArtifact.path` stores the path relative to `<projectRoot>/.fusion/`.
|
|
|
|
### Deletions and filesystem cleanup
|
|
|
|
`deleteService`, `deleteSpec`, and `deleteArtifact` remove DB records. v1 intentionally does **not** remove artifact files from disk; cleanup is deferred to **FN-3767**.
|
|
|
|
## Executor Runtime Exposure
|
|
|
|
When the plugin contributes `executorRuntimeEnv`, executor-spawned task commands receive extra runtime wiring:
|
|
|
|
- Generated CLI artifact directories for each service's latest `generated` spec are prepended to task `PATH` (deduped, absolute paths only).
|
|
- Credentials with `kind: "env_var"` are decoded and injected as environment variables for task subprocesses, including executor agent-session subprocesses (for example `bash` tool commands run inside `createFnAgent(...)`).
|
|
- Non-env credential kinds (`header`, `query_param`, `basic_auth`, `bearer_token`, `api_key`) are intentionally excluded from env injection and remain request-time concerns.
|
|
|
|
Security model:
|
|
|
|
- Runtime env is merged per task (`process.env` base, plugin env overlay, PATH prepend), without mutating global engine `process.env`.
|
|
- Secrets are never logged; executor diagnostics only report counts of injected keys/paths.
|
|
- OAuth credentials are rejected defensively if encountered.
|
|
|
|
To opt out for a service, remove generated artifacts or env-var credentials in the FN-3766-backed service configuration model.
|