@kitman-sh/software-engineering 0.0.0-stage → 0.10.54

package/src/errand.ts

@@ -0,0 +1,142 @@
+import {
+  agentWorkOnce,
+  ask,
+  call,
+  changeRequest,
+  ChangeRequestResult,
+  defineLoop,
+  verify,
+  writeBack
+} from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+import build, { implementAdaptation, SuggestedCheck } from './build'
+import { evidenceTable } from './change-request-body'
+
+const Input = Schema.Struct({
+  /** What to just do. */
+  words: Schema.String,
+  taskId: Schema.optional(Schema.String),
+  repoBindingId: Schema.optional(Schema.String),
+  /** The base branch; the repository's default branch when left out. */
+  branch: Schema.optional(Schema.String)
+})
+
+const Done = Schema.Struct({
+  /** done: finished; blocked: something stopped it; too_big: it is a feature, not an errand, and nothing changed. */
+  status: Schema.Literals(['done', 'blocked', 'too_big']),
+  /** What it did or found, or what stopped it, for the person who asked. */
+  summary: Schema.String,
+  /** Whether it changed any file. */
+  changed: Schema.Boolean,
+  /** The ChangeRequest's title, when it changed files. */
+  title: Schema.optional(Schema.String),
+  /** Checks to run when the repository has none approved. */
+  checks: Schema.optional(Schema.Array(SuggestedCheck))
+})
+
+/** How long an errand may take before it is a feature. */
+const budget = '1 hour'
+
+const choices = ['Open a ChangeRequest', 'Hand to Build for a full review', 'Discard'] as const
+
+const Output = Schema.Struct({
+  status: Schema.Literals(['done', 'blocked', 'too_big', 'opened', 'handed_to_build', 'discarded']),
+  summary: Schema.String,
+  changeRequest: Schema.optional(ChangeRequestResult)
+})
+
+const prompt = (words: string) =>
+  [
+    `Just do this: ${words}`,
+    implementAdaptation,
+    'It is an errand: a rename, a bump, regenerated fixtures, an answer to a question. Do it directly, run the tests of what you touch, and commit nothing you were not asked for.',
+    'If it turns out to be a feature (several parts, design choices, or more than an hour of work), change nothing and answer too_big with why: a Build will do it with a full review. If something stops you, answer blocked with what.',
+    'Answer with a summary for the person who asked, whether you changed files, a ChangeRequest title if you did, and checks to run if the repository has none approved.'
+  ].join('\n\n')
+
+/**
+ * An errand: one agent just does a small thing with the words, with no review rally. A change is verified and then,
+ * by answer or by default, opened as a ChangeRequest marked unreviewed, handed to Build for a full review, or
+ * discarded. A Run that changed nothing ends with the agent's summary; an errand that is really a feature ends by
+ * offering Build with the same words.
+ */
+export default defineLoop({
+  id: 'errand',
+  version: '1.0.0',
+  title: 'Errand',
+  input: Input,
+  output: Output,
+  agents: { implementer: 'implementer' },
+  checkout: 'write',
+  offers: [{ id: 'build', title: 'Build it with a full review', loop: 'build' }],
+  capabilities: ['agent_work', 'verify', 'change_request', 'write_back', 'ask'],
+  calls: () => [build],
+  run: input =>
+    Effect.gen(function* () {
+      const done = yield* agentWorkOnce('errand', {
+        agent: 'implementer',
+        skill: 'implement',
+        prompt: prompt(input.words),
+        output: Done,
+        timeout: budget
+      }).pipe(
+        // Kitman fails a Step that runs past its time budget with this reason.
+        Effect.catchIf(
+          error => error._tag === 'StepFailed' && error.reason.includes('time budget'),
+          () =>
+            Effect.succeed({
+              status: 'too_big' as const,
+              summary: `It took longer than an errand's ${budget}, so it is a feature: Build can do it with a full review.`,
+              changed: false
+            })
+        )
+      )
+
+      if (done.status !== 'done' || !done.changed) return { status: done.status, summary: done.summary }
+
+      const head = yield* verify('verify', { suggested: done.checks ?? [] })
+
+      const answer = yield* ask('next', {
+        prompt: `${done.summary}\n\nThe checks ${head.passed ? 'pass' : 'fail'}. What next?`,
+        options: [
+          { value: 'Open a ChangeRequest', description: 'Deliver it as it is, unreviewed.' },
+          { value: 'Hand to Build for a full review', description: 'Build reviews and verifies it before delivering.' },
+          { value: 'Discard', description: 'Drop the change.' }
+        ] satisfies { readonly value: (typeof choices)[number]; readonly description: string }[],
+        recommended: head.passed ? 'Open a ChangeRequest' : 'Hand to Build for a full review',
+        recommendationReason: head.passed
+          ? 'The checks pass, and an errand is small enough to review on the ChangeRequest.'
+          : 'The checks fail, so it needs the fixes and review a Build gives before anyone merges it.',
+        default: 'Open a ChangeRequest',
+        timeout: '1 hour'
+      })
+
+      if (answer === 'Discard') return { status: 'discarded' as const, summary: done.summary }
+
+      if (answer === 'Hand to Build for a full review') {
+        const built = yield* call('build', build, {
+          words: input.words,
+          revision: head.revision,
+          ...(input.taskId === undefined ? undefined : { taskId: input.taskId }),
+          ...(input.branch === undefined ? undefined : { branch: input.branch })
+        })
+
+        return { status: 'handed_to_build' as const, summary: done.summary, changeRequest: built.changeRequest }
+      }
+
+      const opened = yield* changeRequest('change-request', {
+        title: done.title ?? input.words.slice(0, 120),
+        body: [
+          done.summary,
+          '> **Unreviewed errand.** One agent did this with no review; ask for a Build or a Review if it needs one.',
+          '## Evidence',
+          evidenceTable(head)
+        ].join('\n\n')
+      })
+
+      yield* writeBack('write-back', { milestone: 'change_request_opened', changeRequestUrl: opened.url })
+
+      return { status: 'opened' as const, summary: done.summary, changeRequest: opened }
+    })
+})

package/src/file-tasks.ts

@@ -0,0 +1,30 @@
+import { createTasks, defineLoop, PlanTickets } from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+
+export const FileTasksInput = Schema.Struct({
+  tickets: PlanTickets,
+  /** The Project the Tasks land in; the Project of the Run's Task when left out. */
+  projectId: Schema.optional(Schema.String)
+})
+
+const Output = Schema.Struct({
+  tasks: Schema.Array(Schema.Struct({ key: Schema.String, taskId: Schema.String }))
+})
+
+/** Files tickets as Tasks, with their blockers as dependencies: what another Loop's "File as Tasks" offer starts. */
+export default defineLoop({
+  id: 'file-tasks',
+  version: '1.0.0',
+  title: 'File Tasks',
+  input: FileTasksInput,
+  output: Output,
+  agents: {},
+  checkout: 'none',
+  capabilities: ['create_tasks'],
+  run: input =>
+    createTasks('tasks', {
+      tickets: input.tickets,
+      ...(input.projectId === undefined ? undefined : { projectId: input.projectId })
+    }).pipe(Effect.map(({ tasks }) => ({ tasks })))
+})

package/src/firewatch.ts

@@ -0,0 +1,232 @@
+import { agentWork, alertTask, artifact, ask, call, defineLoop, note } from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Predicate from 'effect/Predicate'
+import * as Schema from 'effect/Schema'
+import build from './build'
+
+const Input = Schema.Struct({
+  /** The alert as the monitoring Connection received it. */
+  alert: Schema.Record(Schema.String, Schema.Json),
+  /** Where a fix is built; the Team's default repository when left out. */
+  repoBindingId: Schema.optional(Schema.String),
+  /** How long a conclusion stands: a repeat within it is folded in, not investigated again; 6 when left out. */
+  windowHours: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(720))),
+  /**
+   * Starts a fix unasked when the cause is in code and the conclusion is confident. A Team opts in with `values` on the
+   * When Clause of the Kit that declares Firewatch for it.
+   */
+  autoFix: Schema.optional(Schema.Boolean)
+})
+
+type Alert = (typeof Input.Type)['alert']
+
+const Conclusion = Schema.Struct({
+  summary: Schema.String,
+  cause: Schema.String,
+  /** high: the evidence shows it; medium: it fits but something is unchecked; low: a best guess. */
+  confidence: Schema.Literals(['high', 'medium', 'low']),
+  /** Logs, metrics, commits or code that support the conclusion. */
+  sources: Schema.NonEmptyArray(Schema.String),
+  /** Each telemetry source tried, and whether it could be read. */
+  telemetry: Schema.Array(
+    Schema.Struct({ source: Schema.String, reached: Schema.Boolean, tried: Schema.optional(Schema.String) })
+  ),
+  /** Whether the cause is in code Kitman can change. */
+  inCode: Schema.Boolean,
+  /** The fix, when the cause is in code. */
+  fix: Schema.optional(Schema.String)
+})
+
+type Conclusion = typeof Conclusion.Type
+
+const FixRequest = Schema.Struct({ words: Schema.String, outcome: Schema.Literal('bug') })
+
+const Output = Schema.Struct({
+  /** folded: a repeat joined earlier work; resolved: it resolved with nothing to investigate; concluded. */
+  status: Schema.Literals(['folded', 'resolved', 'concluded']),
+  taskId: Schema.optional(Schema.String),
+  /** The Run this alert was folded into. */
+  joinedRunId: Schema.optional(Schema.String),
+  conclusionArtifactId: Schema.optional(Schema.String),
+  /** It resolved on its own while it was being investigated. */
+  resolvedDuring: Schema.Boolean,
+  fix: Schema.Literals(['none', 'declined', 'started', 'failed']),
+  changeRequestUrl: Schema.optional(Schema.String),
+  /** The fix a person can still start from the Run's offer. */
+  fixRequest: Schema.optional(FixRequest)
+})
+
+type Output = typeof Output.Type
+
+const firstText = (alert: Alert, ...keys: readonly string[]) =>
+  keys.flatMap(key => {
+    const value = alert[key]
+
+    return Predicate.isString(value) && value.trim() !== '' ? [value] : []
+  })[0]
+
+const alertTitle = (alert: Alert) => firstText(alert, 'title', 'name', 'summary') ?? 'Alert'
+
+/** Names the alert across repeats: its fingerprint, else its title. */
+const fingerprintOf = (alert: Alert) => firstText(alert, 'fingerprint', 'groupKey') ?? alertTitle(alert)
+
+const isResolved = (alert: Alert) => firstText(alert, 'status', 'state')?.toLowerCase() === 'resolved'
+
+const priorities = new Map(
+  Object.entries({
+    critical: 'urgent',
+    p1: 'urgent',
+    urgent: 'urgent',
+    high: 'high',
+    error: 'high',
+    p2: 'high',
+    warning: 'medium',
+    medium: 'medium',
+    p3: 'medium',
+    low: 'low',
+    info: 'low',
+    p4: 'low'
+  } as const)
+)
+
+/** The alert's severity as a Task priority; high when it gives none Kitman knows. */
+const priorityOf = (alert: Alert) => {
+  const severity = firstText(alert, 'severity', 'priority', 'level')?.toLowerCase()
+
+  return (severity === undefined ? undefined : priorities.get(severity)) ?? 'high'
+}
+
+const investigatePrompt = (alert: Alert) =>
+  [
+    'Investigate this alert and conclude what happened and why.',
+    '```json',
+    JSON.stringify(alert, null, 2),
+    '```',
+    'Cite as sources the logs, metrics, commits or code that support your conclusion. List every telemetry source you tried and whether you could read it, with what you tried for one you could not; say how confident you are, lower when a source was out of reach.',
+    'Say whether the cause is in code Kitman can change, and propose a fix only then.'
+  ].join('\n\n')
+
+const conclusionText = (conclusion: Conclusion, resolvedDuring: boolean) =>
+  [
+    conclusion.summary,
+    ...(resolvedDuring ? ['It resolved on its own while it was being investigated.'] : []),
+    `Cause: ${conclusion.cause} (confidence ${conclusion.confidence})`,
+    'Sources:',
+    ...conclusion.sources.map(source => `- ${source}`),
+    ...(conclusion.telemetry.some(source => !source.reached)
+      ? [
+          'Out of reach:',
+          ...conclusion.telemetry
+            .filter(source => !source.reached)
+            .map(source => `- ${source.source}${source.tried === undefined ? '' : `: ${source.tried}`}`)
+        ]
+      : []),
+    ...(conclusion.fix === undefined ? [] : [`Fix: ${conclusion.fix}`])
+  ].join('\n')
+
+/**
+ * Turns an alert into a cited cause on its Bug Task, found by fingerprint or made. A repeat while the alert is being
+ * investigated, or soon after, is folded into that Run as another occurrence. A resolve during the investigation is
+ * stated in the report. A fix in code is offered with a default, so the Run never waits on it: started unasked only
+ * when the Team opted in and the conclusion is confident, else left as an offer on the Run.
+ */
+export default defineLoop({
+  id: 'firewatch',
+  version: '1.0.0',
+  title: 'Firewatch',
+  input: Input,
+  output: Output,
+  outcome: 'investigation',
+  agents: { investigator: 'investigator' },
+  checkout: 'read',
+  when: [{ event: 'monitoring.alert', input: { alert: 'alert' } }],
+  offers: [{ id: 'build-fix', title: 'Build the fix', loop: 'build', from: 'fixRequest' }],
+  capabilities: ['agent_work', 'ask', 'create_tasks'],
+  calls: () => [build],
+  run: input =>
+    Effect.gen(function* () {
+      const fingerprint = fingerprintOf(input.alert)
+      const resolved = isResolved(input.alert)
+      const windowHours = input.windowHours ?? 6
+      const request = { fingerprint, title: alertTitle(input.alert), windowHours, priority: priorityOf(input.alert) }
+
+      const placed = yield* alertTask('task', { ...request, ...(resolved ? { resolved } : undefined) })
+      const taskId = placed.taskId === undefined ? undefined : { taskId: placed.taskId }
+
+      if (placed.joined !== undefined)
+        return {
+          status: 'folded',
+          ...taskId,
+          joinedRunId: placed.joined.runId,
+          resolvedDuring: false,
+          fix: 'none'
+        } satisfies Output
+
+      if (resolved) return { status: 'resolved', ...taskId, resolvedDuring: false, fix: 'none' } satisfies Output
+
+      const conclusion = yield* agentWork('investigate', {
+        agent: 'investigator',
+        prompt: investigatePrompt(input.alert),
+        output: Conclusion
+      })
+
+      // A resolve that arrived while investigating was folded into this Run's Task.
+      const resolvedDuring = (yield* alertTask('task:check', request)).resolved === true
+
+      const stored = yield* artifact('conclusion', {
+        kind: 'investigation_conclusion',
+        title: request.title,
+        text: conclusionText(conclusion, resolvedDuring),
+        data: { alert: input.alert, sources: conclusion.sources, confidence: conclusion.confidence }
+      })
+
+      yield* note('summary', { text: conclusion.summary, artifactId: stored.artifactId })
+
+      const concluded = {
+        status: 'concluded',
+        ...taskId,
+        conclusionArtifactId: stored.artifactId,
+        resolvedDuring
+      } as const
+
+      if (conclusion.fix === undefined || !conclusion.inCode) return { ...concluded, fix: 'none' } satisfies Output
+
+      const fixRequest = {
+        words: `${conclusion.fix}\n\n${conclusionText(conclusion, resolvedDuring)}`,
+        outcome: 'bug' as const
+      }
+
+      const confident = conclusion.confidence === 'high' && !resolvedDuring
+
+      const answer = yield* ask('start-fix', {
+        prompt: `${conclusion.summary}\n\nStart a Build that fixes it as a bug: ${conclusion.fix}?`,
+        options: [
+          { value: 'Start a fix', description: 'A Build fixes it as a bug and opens a ChangeRequest.' },
+          { value: 'Not now', description: 'Keeps the finding on the Task.' }
+        ],
+        recommended: confident ? 'Start a fix' : 'Not now',
+        recommendationReason: confident
+          ? 'Firewatch is confident of the cause and the alert is still firing.'
+          : resolvedDuring
+            ? 'The alert resolved while Firewatch looked, so a fix can wait for a person to judge.'
+            : 'Firewatch is not confident of the cause, so a fix could aim at the wrong thing.',
+        default: input.autoFix === true && confident ? 'Start a fix' : 'Not now',
+        timeout: '1 hour'
+      })
+
+      if (answer === 'Not now') return { ...concluded, fix: 'declined', fixRequest } satisfies Output
+
+      return yield* call('fix', build, {
+        ...fixRequest,
+        ...taskId,
+        ...(input.repoBindingId === undefined ? undefined : { repoBindingId: input.repoBindingId })
+      }).pipe(
+        Effect.map(
+          fixed => ({ ...concluded, fix: 'started', changeRequestUrl: fixed.changeRequest.url }) satisfies Output
+        ),
+        Effect.catchTag('ChildFailed', () =>
+          Effect.succeed({ ...concluded, fix: 'failed', fixRequest } satisfies Output)
+        )
+      )
+    })
+})