@kitman-sh/loops 0.0.0-stage → 0.7.0

package/types/packages/core/src/agent-sandbox-policy.d.ts

@@ -0,0 +1,33 @@
+import * as Schema from 'effect/Schema';
+/** Allowlisted hosts, or `open` for an Agent that browses. */
+export declare const AgentSandboxNetwork: Schema.Union<readonly [Schema.Struct<{
+    readonly hosts: Schema.$Array<Schema.String>;
+}>, Schema.Literal<"open">]>;
+/** What a SandboxBackend enforces around one StepAttempt's Harness; `host` enforces none of it. */
+export declare const AgentSandboxPolicy: Schema.Struct<{
+    readonly writablePaths: Schema.$Array<Schema.String>;
+    /** `~` is the Runner user's home directory. */
+    readonly readDeniedPaths: Schema.$Array<Schema.String>;
+    /** Readable again inside `readDeniedPaths`; a denied path within one stays denied. */
+    readonly readAllowedPaths: Schema.$Array<Schema.String>;
+    readonly network: Schema.Union<readonly [Schema.Struct<{
+        readonly hosts: Schema.$Array<Schema.String>;
+    }>, Schema.Literal<"open">]>;
+    readonly environment: Schema.$Record<Schema.String, Schema.String>;
+    readonly dockerImageDigest: Schema.optionalKey<Schema.String>;
+}>;
+export type AgentSandboxNetwork = (typeof AgentSandboxNetwork)['Type'];
+export type AgentSandboxPolicy = (typeof AgentSandboxPolicy)['Type'];
+/** SSH keys and cloud credentials no sandboxed agent may read. */
+export declare const AgentSandboxCredentialPaths: readonly ['~/.ssh', '~/.aws', '~/.azure', '~/.config/gcloud', '~/.kube', '~/.docker/config.json', '~/.netrc', '~/.git-credentials', '~/.config/gh', '~/.config/glab-cli', '~/.config/kitman/auth.json'];
+/** The Runner's part of a policy; the Agent Backend adds the workspace, the Harness's config and credential. */
+export declare const runnerAgentSandboxPolicy: () => AgentSandboxPolicy;
+/** npm, PyPI, crates.io, the Go module proxy, RubyGems and Maven Central. */
+export declare const PackageRegistryHosts: readonly ['registry.npmjs.org', 'pypi.org', 'files.pythonhosted.org', 'crates.io', 'static.crates.io', 'index.crates.io', 'proxy.golang.org', 'sum.golang.org', 'rubygems.org', 'index.rubygems.org', 'repo.maven.apache.org', 'repo1.maven.org'];
+/** Where an agent Step may connect: Kitman, its Harness's model providers, package registries, its git host and its Agent's own hosts. */
+export declare const agentNetworkAllowlist: (input: {
+    readonly apiUrl: string;
+    readonly providerHosts: readonly string[];
+    readonly repoBindingHost?: string;
+    readonly agent?: AgentSandboxNetwork;
+}) => AgentSandboxNetwork;

package/types/packages/core/src/common.d.ts

@@ -0,0 +1,6 @@
+import * as Schema from 'effect/Schema';
+export declare const Id: Schema.String;
+export declare const Slug: Schema.String;
+export declare const Timestamp: Schema.String;
+export declare const ActorType: Schema.Union<readonly [Schema.Literal<"human">, Schema.Literal<"delegated_agent">, Schema.Literal<"agent">]>;
+export type ActorType = (typeof ActorType)['Type'];

package/types/packages/core/src/context-pack.d.ts

@@ -0,0 +1,182 @@
+import * as Schema from 'effect/Schema';
+export declare const ContextPackModes: readonly ['planning', 'implementation', 'debugging', 'review', 'handoff'];
+export declare const ContextPackIndexEntryKinds: readonly ['task', 'project', 'kit', 'memory', 'decision', 'session', 'session_update', 'proposal', 'task_dependency', 'repo_binding', 'agent_environment', 'loop_step'];
+export declare const ContextPackRetrievalRefKinds: readonly ['kit', 'memory', 'decision', 'session', 'session_update', 'proposal', 'task_dependency', 'repo_binding', 'agent_environment', 'loop_step'];
+export declare const DefaultContextPackMode = "implementation";
+export declare const ContextPackMode: Schema.Union<readonly [Schema.Literal<"planning">, Schema.Literal<"implementation">, Schema.Literal<"debugging">, Schema.Literal<"review">, Schema.Literal<"handoff">]>;
+export declare const ContextPackRetrievalRefKind: Schema.Literals<readonly ["kit", "memory", "decision", "session", "session_update", "proposal", "task_dependency", "repo_binding", "agent_environment", "loop_step"]>;
+export declare const ContextPackLaunchBrief: Schema.Struct<{
+    readonly mode: Schema.Union<readonly [Schema.Literal<"planning">, Schema.Literal<"implementation">, Schema.Literal<"debugging">, Schema.Literal<"review">, Schema.Literal<"handoff">]>;
+    readonly taskTitle: Schema.String;
+    readonly projectName: Schema.optionalKey<Schema.String>;
+    readonly summary: Schema.String;
+}>;
+export declare const ContextPackIndexEntry: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["task", "project", "kit", "memory", "decision", "session", "session_update", "proposal", "task_dependency", "repo_binding", "agent_environment", "loop_step"]>;
+    readonly id: Schema.String;
+    readonly title: Schema.String;
+    readonly reason: Schema.String;
+}>;
+export declare const ContextPackRetrievalRef: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["kit", "memory", "decision", "session", "session_update", "proposal", "task_dependency", "repo_binding", "agent_environment", "loop_step"]>;
+    readonly id: Schema.String;
+    readonly label: Schema.String;
+}>;
+export declare function normalizeContextPackVerificationCommands<InputType>(input: InputType): string[];
+export declare const ContextPackRelevanceSummary: Schema.Struct<{
+    readonly included: Schema.$Array<Schema.String>;
+    readonly omitted: Schema.$Array<Schema.String>;
+    readonly notes: Schema.$Array<Schema.String>;
+    readonly readiness: Schema.optionalKey<Schema.Struct<{
+        readonly scopeAvailable: Schema.Boolean;
+        readonly acceptanceCriteriaAvailable: Schema.Boolean;
+        readonly dependenciesSatisfied: Schema.Boolean;
+        readonly executionPlanAvailable: Schema.Boolean;
+        readonly repoBindingAvailable: Schema.Boolean;
+        readonly verificationCommands: Schema.$Array<Schema.String>;
+        readonly deliveryTargetAvailable: Schema.Boolean;
+    }>>;
+}>;
+export declare const ContextPackBudget: Schema.Struct<{
+    readonly maxMarkdownChars: Schema.Int;
+    readonly markdownChars: Schema.Int;
+    readonly indexedItemCount: Schema.Int;
+    readonly retrievalRefCount: Schema.Int;
+}>;
+export declare const ContextPack: Schema.Struct<{
+    readonly contextPackId: Schema.String;
+    readonly workspaceId: Schema.String;
+    readonly projectId: Schema.optionalKey<Schema.String>;
+    readonly taskId: Schema.String;
+    readonly mode: Schema.Union<readonly [Schema.Literal<"planning">, Schema.Literal<"implementation">, Schema.Literal<"debugging">, Schema.Literal<"review">, Schema.Literal<"handoff">]>;
+    readonly contentMarkdown: Schema.String;
+    readonly launchBrief: Schema.Struct<{
+        readonly mode: Schema.Union<readonly [Schema.Literal<"planning">, Schema.Literal<"implementation">, Schema.Literal<"debugging">, Schema.Literal<"review">, Schema.Literal<"handoff">]>;
+        readonly taskTitle: Schema.String;
+        readonly projectName: Schema.optionalKey<Schema.String>;
+        readonly summary: Schema.String;
+    }>;
+    readonly contextIndex: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["task", "project", "kit", "memory", "decision", "session", "session_update", "proposal", "task_dependency", "repo_binding", "agent_environment", "loop_step"]>;
+        readonly id: Schema.String;
+        readonly title: Schema.String;
+        readonly reason: Schema.String;
+    }>>;
+    readonly retrievalRefs: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["kit", "memory", "decision", "session", "session_update", "proposal", "task_dependency", "repo_binding", "agent_environment", "loop_step"]>;
+        readonly id: Schema.String;
+        readonly label: Schema.String;
+    }>>;
+    readonly relevanceSummary: Schema.Struct<{
+        readonly included: Schema.$Array<Schema.String>;
+        readonly omitted: Schema.$Array<Schema.String>;
+        readonly notes: Schema.$Array<Schema.String>;
+        readonly readiness: Schema.optionalKey<Schema.Struct<{
+            readonly scopeAvailable: Schema.Boolean;
+            readonly acceptanceCriteriaAvailable: Schema.Boolean;
+            readonly dependenciesSatisfied: Schema.Boolean;
+            readonly executionPlanAvailable: Schema.Boolean;
+            readonly repoBindingAvailable: Schema.Boolean;
+            readonly verificationCommands: Schema.$Array<Schema.String>;
+            readonly deliveryTargetAvailable: Schema.Boolean;
+        }>>;
+    }>;
+    readonly budget: Schema.Struct<{
+        readonly maxMarkdownChars: Schema.Int;
+        readonly markdownChars: Schema.Int;
+        readonly indexedItemCount: Schema.Int;
+        readonly retrievalRefCount: Schema.Int;
+    }>;
+    readonly includedKitIds: Schema.$Array<Schema.String>;
+    readonly includedMemoryIds: Schema.$Array<Schema.String>;
+    readonly includedDecisionIds: Schema.$Array<Schema.String>;
+    readonly includedProposalIds: Schema.$Array<Schema.String>;
+    readonly includedSessionIds: Schema.$Array<Schema.String>;
+    readonly createdByActorType: Schema.Union<readonly [Schema.Literal<"human">, Schema.Literal<"delegated_agent">, Schema.Literal<"agent">]>;
+    readonly createdByActorId: Schema.String;
+    readonly createdAt: Schema.String;
+}>;
+export declare const ContextPackGenerate: Schema.Struct<{
+    readonly mode: Schema.optionalKey<Schema.Union<readonly [Schema.Literal<"planning">, Schema.Literal<"implementation">, Schema.Literal<"debugging">, Schema.Literal<"review">, Schema.Literal<"handoff">]>>;
+}>;
+export declare const ContextPackLatestQuery: Schema.Struct<{
+    readonly mode: Schema.optionalKey<Schema.Union<readonly [Schema.Literal<"planning">, Schema.Literal<"implementation">, Schema.Literal<"debugging">, Schema.Literal<"review">, Schema.Literal<"handoff">]>>;
+}>;
+export declare const ContextPackResult: Schema.Struct<{
+    readonly contextPackId: Schema.String;
+    readonly mode: Schema.Union<readonly [Schema.Literal<"planning">, Schema.Literal<"implementation">, Schema.Literal<"debugging">, Schema.Literal<"review">, Schema.Literal<"handoff">]>;
+    readonly contentMarkdown: Schema.String;
+    readonly launchBrief: Schema.optionalKey<Schema.Struct<{
+        readonly mode: Schema.Union<readonly [Schema.Literal<"planning">, Schema.Literal<"implementation">, Schema.Literal<"debugging">, Schema.Literal<"review">, Schema.Literal<"handoff">]>;
+        readonly taskTitle: Schema.String;
+        readonly projectName: Schema.optionalKey<Schema.String>;
+        readonly summary: Schema.String;
+    }>>;
+    readonly contextIndex: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["task", "project", "kit", "memory", "decision", "session", "session_update", "proposal", "task_dependency", "repo_binding", "agent_environment", "loop_step"]>;
+        readonly id: Schema.String;
+        readonly title: Schema.String;
+        readonly reason: Schema.String;
+    }>>>;
+    readonly retrievalRefs: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["kit", "memory", "decision", "session", "session_update", "proposal", "task_dependency", "repo_binding", "agent_environment", "loop_step"]>;
+        readonly id: Schema.String;
+        readonly label: Schema.String;
+    }>>>;
+    readonly relevanceSummary: Schema.optionalKey<Schema.Struct<{
+        readonly included: Schema.$Array<Schema.String>;
+        readonly omitted: Schema.$Array<Schema.String>;
+        readonly notes: Schema.$Array<Schema.String>;
+        readonly readiness: Schema.optionalKey<Schema.Struct<{
+            readonly scopeAvailable: Schema.Boolean;
+            readonly acceptanceCriteriaAvailable: Schema.Boolean;
+            readonly dependenciesSatisfied: Schema.Boolean;
+            readonly executionPlanAvailable: Schema.Boolean;
+            readonly repoBindingAvailable: Schema.Boolean;
+            readonly verificationCommands: Schema.$Array<Schema.String>;
+            readonly deliveryTargetAvailable: Schema.Boolean;
+        }>>;
+    }>>;
+    readonly budget: Schema.optionalKey<Schema.Struct<{
+        readonly maxMarkdownChars: Schema.Int;
+        readonly markdownChars: Schema.Int;
+        readonly indexedItemCount: Schema.Int;
+        readonly retrievalRefCount: Schema.Int;
+    }>>;
+    readonly includedDecisionIds: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly includedProposalIds: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+export declare const ContextPackRetrievalInput: Schema.Struct<{
+    readonly contextPackId: Schema.String;
+    readonly ref: Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["kit", "memory", "decision", "session", "session_update", "proposal", "task_dependency", "repo_binding", "agent_environment", "loop_step"]>;
+        readonly id: Schema.String;
+        readonly label: Schema.String;
+    }>;
+}>;
+export declare const ContextPackRetrievedContext: Schema.Struct<{
+    readonly contextPackId: Schema.String;
+    readonly ref: Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["kit", "memory", "decision", "session", "session_update", "proposal", "task_dependency", "repo_binding", "agent_environment", "loop_step"]>;
+        readonly id: Schema.String;
+        readonly label: Schema.String;
+    }>;
+    readonly contentMarkdown: Schema.String;
+    readonly safety: Schema.Struct<{
+        readonly rawContentIncluded: Schema.Boolean;
+        readonly notes: Schema.$Array<Schema.String>;
+    }>;
+}>;
+export type ContextPackMode = (typeof ContextPackMode)['Type'];
+export type ContextPackRetrievalRefKind = (typeof ContextPackRetrievalRefKind)['Type'];
+export type ContextPackLaunchBrief = (typeof ContextPackLaunchBrief)['Type'];
+export type ContextPackIndexEntry = (typeof ContextPackIndexEntry)['Type'];
+export type ContextPackRetrievalRef = (typeof ContextPackRetrievalRef)['Type'];
+export type ContextPackRelevanceSummary = (typeof ContextPackRelevanceSummary)['Type'];
+export type ContextPackBudget = (typeof ContextPackBudget)['Type'];
+export type ContextPack = (typeof ContextPack)['Type'];
+export type ContextPackGenerate = (typeof ContextPackGenerate)['Type'];
+export type ContextPackLatestQuery = (typeof ContextPackLatestQuery)['Type'];
+export type ContextPackResult = (typeof ContextPackResult)['Type'];
+export type ContextPackRetrievalInput = (typeof ContextPackRetrievalInput)['Type'];
+export type ContextPackRetrievedContext = (typeof ContextPackRetrievedContext)['Type'];

package/types/packages/core/src/extension.d.ts

@@ -0,0 +1,35 @@
+import * as Schema from 'effect/Schema';
+import { SafeJson } from './run';
+export declare const NativeExtensionTarget: Schema.Literals<readonly ["runner_backend", "harness", "sandbox"]>;
+export type NativeExtensionTarget = (typeof NativeExtensionTarget)['Type'];
+/**
+ * Authoring-side reference to a namespaced, versioned native extension. Unknown
+ * identities stay valid so optional payloads survive round trips until a
+ * supporting implementation is selected.
+ */
+export declare const NativeExtensionRef: Schema.Struct<{
+    readonly extensionId: Schema.String;
+    readonly version: Schema.Int;
+    readonly policy: Schema.Literals<readonly ["optional", "required"]>;
+    readonly requiredCapabilities: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly configuration: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<SafeJson, SafeJson, never, never>>>;
+}>;
+export type NativeExtensionRef = (typeof NativeExtensionRef)['Type'];
+/**
+ * Implementation-side descriptor. Exported from implementation-specific modules
+ * only; generic Agents, Steps, Loops, and Kits never import these values.
+ */
+export declare const NativeExtensionDescriptor: Schema.Struct<{
+    readonly extensionId: Schema.String;
+    readonly version: Schema.Int;
+    readonly target: Schema.Literals<readonly ["runner_backend", "harness", "sandbox"]>;
+    readonly requiredCapabilities: Schema.$Array<Schema.String>;
+    readonly configurationSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<SafeJson, SafeJson, never, never>>>;
+    readonly resultSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<SafeJson, SafeJson, never, never>>>;
+    readonly observability: Schema.Struct<{
+        readonly transcriptPolicy: Schema.Literal<"metadata_only">;
+        readonly maxMetadataChars: Schema.optionalKey<Schema.Int>;
+    }>;
+}>;
+export type NativeExtensionDescriptor = (typeof NativeExtensionDescriptor)['Type'];
+export declare function nativeExtensionIdentity(ref: Pick<NativeExtensionRef, 'extensionId' | 'version'>): string;