mas-lab-ctl 0.2.0__py3-none-any.whl

mas/ctl/__init__.py

@@ -0,0 +1,11 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""MAS ctl — compose, placement, session UI, protocol adapters (not the Mealy kernel)."""
+
+from mas.ctl.session.controller import ConversationConfig, SessionController, TurnResult
+
+__all__ = [
+    "ConversationConfig",
+    "SessionController",
+    "TurnResult",
+]

mas/ctl/_schemas/checkpoint.schema.yaml

@@ -0,0 +1,105 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+# Session checkpoint — kernel-only v1 or self-contained session v2.
+$schema: http://json-schema.org/draft-07/schema#
+title: SessionCheckpoint
+oneOf:
+  - type: object
+    required: [version, kernel]
+    additionalProperties: false
+    properties:
+      version: { type: integer, const: 1 }
+      label: { type: string }
+      turn: { type: integer, minimum: 0 }
+      kernel:
+        $ref: "#/definitions/kernel"
+      memory_seeds:
+        type: array
+        items:
+          type: object
+          required: [key, content]
+          additionalProperties: false
+          properties:
+            key: { type: string }
+            content: { type: string }
+      runtime_profile:
+        type: object
+        additionalProperties: true
+        description: Optional design_pattern defaults and gov profile to restore with kernel
+  - type: object
+    required: [version, label, turn, lineage, kernel, working_memory, manifest]
+    additionalProperties: false
+    properties:
+      version: { type: integer, const: 2 }
+      label: { type: string }
+      turn: { type: integer, minimum: 0 }
+      backtrack_count: { type: integer, minimum: 0 }
+      spec_revision: { type: integer, minimum: 0 }
+      related:
+        type: array
+        description: Fingerprints for related-state adapters; bytes stay in the adapter.
+        items:
+          type: object
+          additionalProperties: false
+          properties:
+            plugin: { type: string }
+            fingerprint: { type: string }
+            locator: { type: string }
+            adapter: { type: string }
+      lineage:
+        type: object
+        required: [session_id, parent_session_id, forked_from_checkpoint, root_session_id, created_at]
+        additionalProperties: false
+        properties:
+          session_id: { type: string, minLength: 1 }
+          parent_session_id: { type: [string, "null"] }
+          forked_from_checkpoint: { type: [string, "null"] }
+          root_session_id: { type: [string, "null"] }
+          created_at: { type: string, format: date-time }
+      kernel:
+        $ref: "#/definitions/kernel"
+      working_memory:
+        type: array
+        items:
+          type: object
+          required: [agent_id, turn_history, committed_messages, conversation_chunks]
+          additionalProperties: false
+          properties:
+            agent_id: { type: string, minLength: 1 }
+            turn_history:
+              type: array
+              items:
+                type: array
+                minItems: 2
+                maxItems: 2
+                items: { type: string }
+            committed_messages:
+              type: array
+              items: { type: object, additionalProperties: true }
+            conversation_chunks: { type: [object, "null"], additionalProperties: true }
+            working_messages:
+              type: array
+              items: { type: object, additionalProperties: true }
+            open_tool_call_id: { type: string }
+            synced_tool_result_cids:
+              type: array
+              items: { type: integer }
+      manifest:
+        type: object
+        required: [content, content_hash]
+        additionalProperties: false
+        properties:
+          content: { type: object, additionalProperties: true }
+          content_hash: { type: string, pattern: "^[a-f0-9]{64}$" }
+      memory_seeds:
+        type: array
+        items: { type: object, additionalProperties: true }
+      runtime_profile:
+        type: object
+        additionalProperties: true
+definitions:
+  kernel:
+    type: object
+    description: RuntimeKernel.snapshot() — Q_product and run ledger
+    required: [q, run]
+    additionalProperties: true

mas/ctl/_schemas/component-registry.yaml

@@ -0,0 +1,48 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+# Component registry — authoritative IDs for ctl/runtime adapters.
+# Deployment.spec.runtime_id, placement strategy, and framework adapter MUST use these ids.
+apiVersion: mas/v1
+kind: ComponentRegistry
+metadata:
+  name: mas-lab-components
+spec:
+  runtimes:
+    - id: mas-runtime-py
+      layer: ctl.runtime
+      module: mas.ctl.compose.backends.mas_runtime_py.MasRuntimePyKernelBackend
+      description: Python Mealy kernel (provable product, local-inproc)
+
+  placement:
+    - id: local-inproc
+      layer: ctl.placement
+      module: mas.ctl.compose.placement_registry.LocalInprocBackend
+      description: In-process comm bus (OSS-supported)
+      status: available
+    - id: local-multiprocess
+      layer: ctl.placement
+      module: null
+      status: planned
+      description: Planned — not in this OSS release
+    - id: docker
+      layer: ctl.placement
+      module: mas.ctl.placement.docker.DockerBackend
+      status: planned
+      description: Planned — not in this OSS release
+    - id: kubernetes
+      layer: ctl.placement
+      module: mas.ctl.placement.k8s.K8sBackend
+      status: planned
+      description: Planned — not in this OSS release
+
+  framework:
+    - id: native
+      layer: ctl.framework
+      module: mas.ctl.compose.framework_registry.NativeFrameworkAdapter
+    - id: langgraph
+      layer: ctl.framework
+      module: mas.ctl.compose.framework_registry.LangGraphFrameworkAdapter
+    - id: crewai
+      layer: ctl.framework
+      module: null
+      status: planned

mas/ctl/_schemas/config.schema.yaml

@@ -0,0 +1,262 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+$schema: "http://json-schema.org/draft-07/schema#"
+$id: "mas.config/config/v1"
+title: "config.yaml"
+description: >
+  Project workspace configuration discovered by walking up from the current
+  directory (or from MAS_WORKSPACE_ROOT). Secrets belong in the file named by
+  mas_ctl.env (default .env) — never in this YAML.
+
+type: object
+additionalProperties: false
+properties:
+  mas_ctl:
+    type: object
+    additionalProperties: false
+    description: Defaults for mas-ctl chat / run-mas / validate.
+    properties:
+      flavour:
+        type: string
+        default: local
+        description: >-
+          Flavour name (library-standard bundle, e.g. local). Resolved to
+          flavours/<name>.yaml under the workspace or installed library.
+      env:
+        type: string
+        default: .env
+        description: Gitignored secrets file relative to workspace root.
+      deployment:
+        type: string
+        description: Optional deployment manifest path (relative to workspace).
+      runtime_id:
+        type: string
+        description: Kernel/runtime id override.
+      runtime_profile:
+        type: string
+        description: Path to runtime-profile manifest (relative to workspace).
+      cache:
+        type: string
+        enum: [read-only]
+        description: >-
+          Default cache mode for mas-ctl chat / serve. `read-only` answers from the recorded
+          answers only (no LLM call, no cache write, no API key), like `--cache-read-only`.
+          Omit it to call the model on a cache miss.
+      trace:
+        description: >-
+          Human exchange log on stderr for mas-ctl chat / run-mas. `summary`
+          (or `true`) is the usable default: headers + timestamps, untruncated
+          AGENT→USER. `full` dumps payloads. `off` (or `false`) disables.
+          Color is never implied; set trace_color or pass --trace-color.
+          Machine data is events.jsonl / mas-lab telemetry, not this log.
+        oneOf:
+          - type: boolean
+          - type: string
+            enum: [off, summary, full]
+        default: off
+      trace_timestamps:
+        type: boolean
+        default: true
+        description: UTC + elapsed on each exchange (on by default when tracing).
+      trace_color:
+        type: boolean
+        default: false
+        description: ANSI color on the exchange log. Never the CLI default.
+      trace_engine:
+        type: boolean
+        default: false
+        description: Include raw InvokeEngineIo / EngineIoReturn JSON.
+      archive:
+        type: object
+        additionalProperties: false
+        description: >
+          Conversation archive (full session log). Complementary to traces/.
+          Off by default so experiments at scale do not fill the disk.
+          Enable only for reverse debugging / shallow checkpoints.
+        properties:
+          enabled:
+            type: boolean
+            default: false
+            description: >
+              Persist every archive chunk under traces/<dir_name> when an
+              events file is set. false keeps the archive in RAM only and
+              forces deep checkpoints.
+          dir_name:
+            type: string
+            default: archive
+            description: Folder name colocated with events.jsonl (traces/archive).
+          memory_watermark_bytes:
+            type: integer
+            minimum: 0
+            default: 67108864
+            description: >
+              RAM cache cap after chunks are on disk. Folded leaves drop
+              from memory past this watermark. 0 = keep every payload in RAM.
+
+  mas_lab:
+    type: object
+    additionalProperties: false
+    description: Defaults for mas-lab benchmark and demo commands.
+    properties:
+      flavour:
+        type: string
+        default: local
+      benchmark_flavour:
+        type: string
+        description: Flavour used when running benchmark experiments.
+      benchmark:
+        type: object
+        additionalProperties: false
+        description: Defaults for ``mas-lab benchmark run`` stale-output handling.
+        properties:
+          clean_stale_outputs:
+            type: boolean
+            default: false
+            description: >-
+              When true, remove benchmark output folders for scenarios no longer
+              declared in experiment.yaml before each run.
+          clean_stale_trace_cache:
+            type: boolean
+            default: true
+            description: >-
+              When cleaning stale benchmark outputs, also remove trace-cache
+              entries (data/cache/traces/<hash>/) whose reference count reaches zero.
+      labs_search_paths:
+        oneOf:
+          - type: string
+          - type: array
+            items:
+              type: string
+        description: >-
+          Directories scanned for ``*.lab`` folders (relative to the config file,
+          or absolute). An entry may itself be a ``*.lab`` directory. When this
+          key is present (including an empty list) it is the exclusive lab
+          catalog. When omitted, installed packages and cwd-walk stay additive.
+          Separate from ``paths.labs_dir`` (benchmark output). New labs are
+          created under the first entry.
+
+  plugins:
+    description: >-
+      Workspace plugins (gdb, checkpoint stores). Off unless listed. The init
+      template comments every catalog URN; uncomment ``plugins:`` and a line
+      to enable it. Labs may
+      enable the same URNs as ``lab.enable_plugins``. Specs that already name
+      a plugin keep their own config.
+    oneOf:
+      - type: array
+        items:
+          type: string
+          minLength: 1
+      - type: object
+        additionalProperties:
+          type: boolean
+
+  infra_refs:
+    oneOf:
+      - type: string
+      - type: array
+        items:
+          type: string
+    description: >-
+      Infra bundle refs merged left-to-right (e.g. standard:openai,
+      standard:llm-proxy, or a workspace-relative LLMProxy path). Override at
+      runtime with env var MAS_INFRA_REFS (comma- or space-separated) without
+      editing this file; CLI --infra-ref still wins.
+
+  runtime_refs:
+    oneOf:
+      - type: string
+      - type: array
+        items:
+          type: string
+    description: >-
+      RuntimeEngine manifest refs merged left-to-right (e.g.
+      standard:runtime-default or a workspace-relative path under runtime/).
+      Omit entirely to use package defaults only. Override with env var
+      MAS_RUNTIME_REFS (comma- or space-separated).
+
+  middleware:
+    oneOf:
+      - type: string
+      - type: array
+        items:
+          type: string
+    description: >
+      Infra middleware bundle refs merged after infra_refs.
+      infra_interceptors is a read-only alias; mixing both is an error.
+
+  infra_interceptors:
+    oneOf:
+      - type: string
+      - type: array
+        items:
+          type: string
+    description: Read-only alias of middleware.
+
+  manifest_libraries:
+    description: >-
+      Extra library **search folders** for this workspace. Same scan as
+      ``lab.libraries`` and ``MAS_LIBRARY_PATHS``: each path is a library
+      root, or a parent of sibling library folders. ``library.yaml`` in
+      those folders fills the catalog. Names come from the found
+      directory stem. A legacy name→path map is flattened to its path
+      values; it is not an alias table.
+    oneOf:
+      - type: array
+        items:
+          type: string
+          minLength: 1
+      - type: object
+        additionalProperties:
+          type: string
+
+  aliases:
+    type: object
+    additionalProperties:
+      type: string
+    description: >-
+      Alias overrides for runtime plugin lookup. Keys are human-friendly names
+      or legacy aliases; values are canonical plugin URNs such as
+      mas.dp.react.
+
+  defaults:
+    type: object
+    additionalProperties: false
+    description: >-
+      Overrides merged over the runtime's built-in defaults.yaml (per key,
+      workspace value wins). See runtime/docs/agent-defaults.md.
+    properties:
+      model:
+        type: string
+        description: Fill-in LLM id for remaining Agent/MAS/experiment `any` after experiment.models (not written into committed specs).
+      design_pattern:
+        type: string
+        description: Default plugin id for spec.design_pattern when manifests omit one.
+      context_manager:
+        type: string
+        description: Default plugin id for spec.context_manager when manifests omit one.
+      assembler:
+        type: string
+        description: Default plugin id for spec.assembler when manifests omit one.
+
+  paths:
+    type: object
+    additionalProperties: false
+    description: >-
+      Optional path overrides (otherwise $XDG_CONFIG_HOME/mas/config.yaml paths
+      or MAS_* env vars; see docs/user-config.md).
+    properties:
+      labs_dir:
+        type: string
+        description: Default root for benchmark run output (metadata.yaml, results.csv).
+      cache_dir:
+        type: string
+      runs_dir:
+        type: string
+      archive_dir:
+        type: string
+        description: >
+          Folder for the conversation archive after mas_ctl.archive.enabled
+          is true. Setting this path does not turn persist on. Absolute
+          paths win. Relative paths resolve from the app root. Not an
+          agent spec field.

mas/ctl/_schemas/contracts-registry.yaml

@@ -0,0 +1,104 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+# v2 plugin contract registry — maps contract IDs to TLA machines and Python modules.
+# Authority: docs/design/plugin-contracts.md
+apiVersion: mas/v1
+kind: ContractRegistry
+metadata:
+  name: mas-lab-contracts
+spec:
+  contracts:
+    - id: DesignPatternPlugin
+      alias: [MealyPlugin, DesignPatternContract, M_dp]
+      tla: DesignPatternScheduler.tla
+      module: mas.runtime.machines.design_pattern.protocol
+      ingress: [USER_INPUT_RECEIVED, CTX_ASSEMBLY_COMPLETE, ENGINE_IO_RETURN, HITL_RESOLVE]
+      egress: [REQUEST_CTX_ASSEMBLY, INVOKE_ENGINE_IO, EMIT_CLIENT_RESPONSE, EMIT_HITL_REQUEST]
+      implementations:
+        - react@v1
+        - cot@v1
+        - single_pass@v1
+
+    - id: EngineContract
+      alias: [M_model, M_tool, execution_engine]
+      tla: EngineEnvironment.tla
+      module: mas.runtime.engine.protocol
+      ingress: [InvokeEngineIo via driver]
+      egress: [EngineIoReturn]
+      implementations:
+        - SimulatedEngine
+        - LiveLlmEngine
+
+    - id: CtxAssembler
+      alias: [CtxAssemblerContract, M_ctx]
+      tla: ContextMachine.tla
+      module: mas.runtime.boundary.context.protocol
+      ingress: [RequestCtxAssembly]
+      egress: [CtxAssemblyComplete]
+      implementations:
+        - AutoCtxAssembler
+
+    - id: HitlResponder
+      alias: [M_gov_hitl]
+      tla: Governance.tla
+      module: mas.runtime.boundary.hitl.responders
+      ingress: [EmitHitlRequest]
+      egress: [HitlResolve]
+      implementations:
+        - AutoApproveResponder
+
+    - id: ObservabilitySink
+      alias: [M_obs]
+      tla: Observability.tla
+      module: mas.runtime.boundary.obs.protocol
+      implementations:
+        - ObservabilityOperator
+
+    - id: EnvelopeProduct
+      alias: [M_envelope, execute_contract_call]
+      tla: EnvelopeProduct.tla
+      tla_root: external-formal-repo/tla/specs
+      note: Formal TLA specs — maintained outside this OSS release
+      module: mas.runtime.kernel.envelope
+      ingress: [observability_post_execute, contract_end, governance_validate]
+      egress: [obs_wrap_gov_authorize, governance_authorize, contract_start, observability_pre_execute]
+      note: Profile flags EnableGov / EnableObs collapse σ schedule
+
+    - id: EventEmitter
+      alias: [obs_terminating_protocol]
+      module: mas.library.standard.lib.observability.emit
+      note: Terminating protocol — JSONL file or stderr
+      implementations:
+        - JsonlFileEmitter
+        - StdoutJsonlEmitter
+
+    - id: ObservabilityExportPlugin
+      module: mas.library.standard.plugins.observability
+      mode: read
+      note: Manifest-declared export plugins (native, otel, ioa_observe)
+      implementations:
+        - NativeObservabilityPlugin
+        - OtelObservabilityPlugin
+
+    - id: LLMProvider
+      alias: [ModelAccess, llm_provider]
+      module: mas.runtime.registry.llm_provider_protocol
+      note: Wire-protocol plugins for chat completions. Cache wraps a routed protocol; offline CI uses llm_cache replay.
+      implementations:
+        - OpenAILLMProvider
+        - CacheLLMProvider
+
+    - id: EventTransform
+      module: mas.library.standard.lib.observability.native.transform
+      note: Pure native projection (OTel via MasOtelConverter, not transform hack)
+      implementations:
+        - NativeObservabilityTransform
+        - BoundaryPassthroughTransform
+
+  v1_migration:
+    ToolContract: EngineContract.TOOL_CALL
+    ModelContract: EngineContract.LLM_CALL
+    PromptContract: CtxAssembler
+    MemoryContract: EngineContract.MEMORY_OP
+    DPContract: DesignPatternPlugin
+    SurfaceAdapter: mas.ctl.ui.ConversationDisplay